Development
Contributing to MetaMCP
Learn how to contribute to MetaMCP development and help improve the project
We welcome contributions to MetaMCP! This comprehensive guide will help you get started with contributing to the project, whether you’re fixing bugs, adding features, or improving documentation.
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