Notion MCP Server

Verified
Note Taking
MIT License
OverviewInspectSchema Related Servers Reviews Score
# Contributing to Notion MCP Server

First off, thank you for considering contributing to the Notion MCP Server! This is an open-source project that helps integrate Notion with Large Language Models through the Model Context Protocol.

## Code of Conduct

By participating in this project, you are expected to uphold our Code of Conduct of treating all contributors with respect and maintaining a harassment-free experience for everyone.

## How Can I Contribute?

### Reporting Bugs

Before submitting a bug report:
- Check the existing issues to avoid duplicates
- Collect relevant information about the bug
- Use the bug report template below

**Bug Report Template:**
```markdown
**Description**
A clear description of the bug.

**To Reproduce**
Steps to reproduce the behavior:
1. Configure server with '...'
2. Call tool '...'
3. See error

**Expected behavior**
What you expected to happen.

**Actual behavior**
What actually happened.

**Environment**
- Node.js version:
- Operating System:
- Notion MCP Server version:
```

### Suggesting Enhancements

When suggesting enhancements:
- Use a clear and descriptive title
- Provide a detailed description of the proposed functionality
- Include examples of how the enhancement would be used

### Pull Requests

1. Fork the repository
2. Create a new branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests if available
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to your branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

#### Pull Request Guidelines

- Follow the existing code style
- Update documentation as needed
- Add tests if applicable
- Keep pull requests focused on a single feature or fix

## Development Setup

1. Clone your fork:
```bash
git clone https://github.com/your-username/notion-server.git
cd notion-server
```

2. Install dependencies:
```bash
npm install
```

3. Create a `.env` file:
```env
NOTION_API_KEY=your_notion_api_key_here
```

4. Build the project:
```bash
npm run build
```

## Style Guidelines

### TypeScript Style Guide

- Use TypeScript for all new code
- Follow existing code formatting
- Use meaningful variable and function names
- Add appropriate type annotations
- Document complex logic with comments

### Commit Messages

- Use clear and meaningful commit messages
- Start with a verb in the present tense
- Keep the first line under 50 characters
- Add detailed description if needed

Examples:
```
Add page deletion tool
Fix error handling in search_pages
Update documentation for create_page
```

## Adding New Tools

When adding new tools:

1. Define the tool in `TOOL_DEFINITIONS`:
```typescript
{
    name: "tool_name",
    description: "Clear description of what the tool does",
    inputSchema: {
        type: "object",
        properties: {
            // Define input parameters
        },
        required: []
    }
}
```

2. Implement the handler in `toolHandlers`
3. Add appropriate error handling
4. Update documentation
5. Add examples in README.md

## Testing

- Test your changes with different inputs
- Verify error handling
- Test integration with Claude Desktop or other MCP clients
- Document any new test cases added

## Documentation

- Update README.md for new features
- Add JSDoc comments for new functions
- Update type definitions as needed
- Include examples for new functionality

## Questions?

Feel free to open an issue for:
- Help with development
- Questions about contributing
- Clarification on project direction

## License

By contributing, you agree that your contributions will be licensed under the MIT License.