# Contributing to Deep Graph MCP Server
Thank you for your interest in contributing to the Deep Graph MCP Server! This document provides guidelines for development setup, testing, and the pull request process.
## Development Setup
### Prerequisites
- Node.js (version 18 or higher)
- npm or pnpm (pnpm is preferred, as specified in package.json)
- Git
### Initial Setup
1. **Fork and clone the repository**
```bash
git clone https://github.com/JudiniLabs/mcp-code-graph.git
cd mcp-code-graph
```
2. **Install dependencies**
```bash
# Using pnpm (recommended)
pnpm install
# Or using npm
npm install
```
3. **Set up environment variables**
Create a `.env` file in the root directory:
```bash
CODEGPT_API_KEY=your_api_key_here
CODEGPT_ORG_ID=your_org_id_here # Optional
CODEGPT_GRAPH_ID=your_graph_id_here # Optional
```
### Development Commands
```bash
# Build the project
npm run build
# Build and watch for changes during development
npm run watch
# Test the MCP server locally
node dist/index.js
# Debug MCP server with wrapper
node debug-mcp.js
```
### Project Structure
- **src/index.ts**: Main MCP server implementation with all tool definitions
- **debug-mcp.js**: Wrapper script for debugging ES module compatibility
- **dist/**: Compiled JavaScript output (generated by TypeScript)
- **CLAUDE.md**: Project instructions for Claude Code integration
## Testing Guidelines
### Manual Testing
Since this project doesn't currently have automated tests, manual testing is essential:
1. **Build the project** to ensure TypeScript compilation succeeds:
```bash
npm run build
```
2. **Test MCP server locally**:
```bash
node dist/index.js
```
3. **Test with MCP client** (Claude Desktop, Cursor, etc.):
- Configure your MCP client to use the local server
- Test each of the 6 main tools:
- `list-graphs`
- `get-code`
- `find-direct-connections`
- `nodes-semantic-search`
- `docs-semantic-search`
- `get-usage-dependency-links`
4. **Test different configurations**:
- With and without `CODEGPT_GRAPH_ID` set
- With and without `CODEGPT_ORG_ID` set
- Test command-line argument passing
### Testing Checklist
Before submitting a PR, ensure:
- [ ] Project builds successfully (`npm run build`)
- [ ] No TypeScript compilation errors
- [ ] MCP server starts without errors
- [ ] All 6 tools are accessible and respond appropriately
- [ ] Error handling works for invalid inputs
- [ ] Environment variable configuration works
- [ ] Command-line argument parsing works
## Pull Request Process
### Before Submitting
1. **Create a feature branch** from `main`:
```bash
git checkout -b feature/your-feature-name
```
2. **Make your changes** following the existing code style:
- Use TypeScript with strict typing
- Follow existing naming conventions
- Add appropriate error handling
- Update CLAUDE.md if architectural changes are made
3. **Test thoroughly** using the manual testing guidelines above
4. **Update documentation** if needed:
- Update README.md for user-facing changes
- Update CLAUDE.md for development-related changes
- Add JSDoc comments for new functions
### Submitting Your PR
1. **Commit your changes** with clear, descriptive messages:
```bash
git add .
git commit -m "feat: add new semantic search functionality"
```
2. **Push to your fork**:
```bash
git push origin feature/your-feature-name
```
3. **Open a Pull Request** with:
- Clear title describing the change
- Detailed description of what was changed and why
- Testing steps you performed
- Any breaking changes or migration notes
### PR Requirements
- [ ] All builds pass successfully
- [ ] Manual testing completed
- [ ] Code follows existing style conventions
- [ ] Documentation updated if necessary
- [ ] No breaking changes (or clearly documented)
- [ ] Commit messages are clear and descriptive
### Code Review Process
1. At least one maintainer will review your PR
2. Address any feedback or requested changes
3. Once approved, a maintainer will merge your PR
4. Your changes will be included in the next release
## Code Style Guidelines
- Use TypeScript with strict type checking
- Follow existing indentation and formatting
- Use meaningful variable and function names
- Add JSDoc comments for public APIs
- Handle errors gracefully with appropriate logging
- Use async/await for asynchronous operations
## Getting Help
If you need help with development:
- Check existing issues for similar problems
- Review the codebase and CLAUDE.md for architectural guidance
- Open a discussion for design questions
- Contact support@codegpt.co for CodeGPT API questions
## License
By contributing to this project, you agree that your contributions will be licensed under the MIT License.
