Getting Started
Prerequisites
Before contributing, ensure you have:- Node.js 18+ and pnpm installed
- Docker for running PostgreSQL and testing
- Git for version control
- Basic understanding of TypeScript, React, and MCP protocol
Development Setup
Fork and Clone
Fork and Clone
- Fork the repository on GitHub
- Clone your fork locally:
- Add upstream remote:
Install Dependencies
Install Dependencies
Install project dependencies using pnpm:This will install dependencies for all workspaces in the monorepo.
Environment Setup
Environment Setup
Set up your development environment:Modify the
.env file as needed for your development setup.Database Setup
Database Setup
Start PostgreSQL using Docker:First time migration (edit
.env.local first)Development Workflow
Creating a Feature Branch (naming not required)
Making Changes
Follow these guidelines when making changes:Code Quality Standards
- Follow TypeScript best practices
- Use ESLint and Prettier for consistent formatting
- Write descriptive commit messages
- Add JSDoc comments for complex functions
- Ensure type safety throughout the codebase
- Test your changes manually
Testing Your Changes
Local Testing
Local Testing
Run the development server and test your changes:This starts both frontend and backend in development mode.
Linting and Formatting
Linting and Formatting
Ensure code quality:
Docker Testing
Docker Testing
Test with Docker to ensure production compatibility:
Types of Contributions
Bug Fixes
Reporting Bugs
Reporting Bugs
Before reporting a bug:
- Check existing issues to avoid duplicates
- Try to reproduce the issue consistently
- Gather relevant information (OS, browser, MetaMCP version)
- Include steps to reproduce the problem
Fixing Bugs
Fixing Bugs
When fixing bugs:
- Create a branch:
fix/issue-number-description - Implement the fix
- Test manually to ensure the fix works
- Update documentation if necessary
Feature Development
Proposing Features
Proposing Features
Before implementing a new feature:
- Open an issue to discuss the feature
- Provide use cases and justification
- Consider impact on existing functionality
- Get feedback from maintainers
- Plan the implementation approach
Implementing Features
Implementing Features
Feature development process:
- Create feature branch from main
- Implement incrementally with regular commits
- Update documentation
- Test with real MCP servers
- Consider i18n impact for UI changes
Documentation
Documentation Guidelines
Documentation Guidelines
When updating documentation:
- Use clear, concise language
- Include code examples where helpful
- Add screenshots for UI changes
- Update both README and docs site
- Test all code examples
- Consider multiple audiences (beginners, advanced users)
Translation Contributions
Translation Contributions
Adding new language support:
- Create new locale directory:
public/locales/[locale]/ - Copy English files as templates
- Translate content maintaining key structure
- Update i18n configuration
- Test the new locale thoroughly
- Submit PR with translation files
Pull Request Process
Before Submitting
Pre-submission Checklist
- ✅ Code follows project standards
- ✅ Fix liniting as much as possible (somewhat tolerant as we dev rapidly) (
pnpm lint) - ✅ No TypeScript errors
- ✅ Documentation updated if needed
- ✅ Changes tested manually
- ✅ Database migrations included if needed
- ✅ No sensitive information in commits
Specialized Contributions
OIDC Provider Setup
MetaMCP supports OpenID Connect for enterprise SSO. When working on OIDC features:OIDC Configuration
OIDC Configuration
Required environment variables:
Testing OIDC
Testing OIDC
For OIDC development:
- Use a test provider (Auth0, Keycloak)
- Configure redirect URI:
${APP_URL}/api/auth/oauth2/callback/oidc - Test the authentication flow
- Verify user creation in database
- Enable debug logging for troubleshooting
Database Changes
When making database schema changes:Schema Migrations
Schema Migrations
Creating migrations:
Adding New Tables
Adding New Tables
Database development workflow:
- Update schema in
apps/backend/src/db/schema.ts - Create repository in
apps/backend/src/db/repositories/ - Create serializer in
apps/backend/src/db/serializers/ - Add tRPC procedures in
apps/backend/src/trpc/ - Update frontend types in
packages/zod-types/ - Generate and apply migrations
Frontend Development
UI Components
UI Components
Using shadcn/ui components:Component guidelines:
- Follow existing design patterns
- Ensure accessibility compliance
- Add proper TypeScript types
- Include loading and error states
Internationalization
Internationalization
For UI changes:
- Add English translations first
- Update other locales or mark for translation
- Use the
useTranslations()hook - Test with different languages
- Ensure text expansion doesn’t break layout
Community Guidelines
Code of Conduct
We’re committed to providing a welcoming and inclusive environment:Community Standards
- Be respectful and inclusive in all interactions
- Provide constructive feedback and be open to receiving it
- Focus on collaboration and helping each other succeed
- Respect different perspectives and experience levels
- Follow project guidelines and maintain code quality
Communication
Discord Community
Discord Community
Join our Discord server for:
- Development discussions
- Getting help with contributions
- Sharing ideas and feedback
- Community announcements
GitHub Discussions
GitHub Discussions
Use GitHub Issues and Discussions for:
- Bug reports and feature requests
- Technical discussions
- Documentation feedback
- Project roadmap discussions
Getting Help
Resources
Recognition
We appreciate all contributions to MetaMCP! Contributors are recognized through:- GitHub contributors list on the repository
- Release notes mentioning significant contributions