contributing.md

Contributing Guide

Thank you for your interest in contributing to fedramp-docs-mcp! This guide covers how to contribute effectively.

Getting Started

1. Fork the repository on GitHub

2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/fedramp-docs-mcp.git
   cd fedramp-docs-mcp

3. Set up development environment:

   npm install
   npm run build

See Local Development Setup for detailed instructions.

Ways to Contribute

Report Bugs

Found a bug? Open an issue with:

• Node.js version
• Operating system
• Steps to reproduce
• Expected vs actual behavior
• Error messages (if any)

Suggest Features

Have an idea? Open an issue describing:

• The problem you're trying to solve
• Your proposed solution
• Alternative approaches considered

Improve Documentation

Documentation improvements are always welcome:

• Fix typos or unclear wording
• Add examples
• Improve guides
• Update outdated information

Submit Code

Code contributions should:

• Include tests for new functionality
• Pass existing tests
• Follow the code style
• Include documentation updates

Development Workflow

1. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

2. Make Changes

# Run in development mode
npm run dev

# Run tests as you work
npm test

3. Test Your Changes

# Run all tests
npm test

# Run linting
npm run lint

# Build to check for TypeScript errors
npm run build

4. Test with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Open http://localhost:6274 and test your changes interactively.

5. Commit Your Changes

git add .
git commit -m "feat: add new functionality"

Follow Conventional Commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation only
• test: - Tests only
• refactor: - Code refactoring
• chore: - Build/tooling changes

6. Push and Create PR

git push origin feature/your-feature-name

Open a Pull Request on GitHub with:

• Clear description of changes
• Reference to related issues
• Test results

Code Style

TypeScript

• Use TypeScript strict mode
• Add types for all function parameters and returns
• Prefer interface over type for object shapes
• Use meaningful variable names

Formatting

The project uses ESLint and Prettier:

# Check formatting
npm run lint

# Auto-fix issues
npm run lint:fix
npm run format

Testing

• Write tests for new functionality
• Keep tests focused and readable
• Mock external dependencies

Project Structure

fedramp-docs-mcp/
├── src/
│   ├── index.ts           # Entry point
│   ├── tools/             # MCP tool implementations
│   │   ├── ksi.ts         # KSI-related tools
│   │   ├── controls.ts    # Control mapping tools
│   │   └── ...
│   ├── utils/             # Shared utilities
│   └── types/             # TypeScript types
├── tests/                 # Test files
├── docs/                  # Documentation
└── dist/                  # Build output (generated)

Adding a New Tool

1. Create tool implementation in src/tools/:

export async function myNewTool(params: MyToolParams): Promise<MyToolResult> {
  // Implementation
}

2. Register the tool in src/index.ts:

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    // ... existing tools
    {
      name: 'my_new_tool',
      description: 'What this tool does',
      inputSchema: {
        type: 'object',
        properties: {
          param1: { type: 'string', description: '...' }
        }
      }
    }
  ]
}));

3. Add tests in tests/:

describe('myNewTool', () => {
  it('should do something', async () => {
    const result = await myNewTool({ param1: 'value' });
    expect(result).toBeDefined();
  });
});

4. Update documentation in docs/reference/tools.md

Review Process

Pull requests are reviewed for:

• Functionality - Does it work correctly?
• Tests - Are there adequate tests?
• Code quality - Is it readable and maintainable?
• Documentation - Is it documented?
• Compatibility - Does it work with existing features?

Expect feedback and iteration. This is normal and helps ensure quality.

Release Process

Maintainers handle releases:

1. Update version in package.json
2. Update CHANGELOG.md
3. Create git tag
4. Publish to npm
5. Update MCP Registry

Questions?

• GitHub Issues - For bugs and features
• GitHub Discussions - For questions and ideas

Code of Conduct

Be respectful and constructive. We're all here to make FedRAMP compliance easier.

License

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