# Contributing to DevDocs-MCP

First off, thank you for considering contributing to DevDocs-MCP! It's people like you who make this tool better for everyone.

## 🛠️ Development Setup

The project is built with NestJS. To get started:

1. **Clone the Repository**:

    ```bash
    git clone https://github.com/madhan-g-p/DevDocs-MCP.git
    cd DevDocs-MCP
    ```

2. **Install Dependencies**:

    ```bash
    pnpm install
    ```

3. **Build the Project**:

    ```bash
    pnpm run build
    ```

4. **Run in Development Mode**:

    ```bash
    pnpm run start:dev
    ```

> **Important:** Contributors must use `pnpm` strictly to avoid dependency issues and ensure consistency.

## 📐 Project Philosophy

- **Zero Native Builds**: This project uses `sql.js` specifically to avoid external toolchain dependencies (no Python/C++ compiler required). Do NOT add libraries that require `node-gyp` or native compilation.
- **Documentation-First**: If you add a new tool, ensure it follows the MCP specification and is clearly documented in `ARCHITECTURE.md`.
- **Input Validation**: All tools must strictly validate inputs. Refer to `src/tools/project.tool.ts` for examples.

## 🧪 Testing

This project is supposed to use Jest for unit and integration testing.

```bash
# Run tests
pnpm test

# Run tests in watch mode
pnpm run test:watch
```

## 👨‍💻 Code Style

This project uses **ESLint** and **Prettier**. Please ensure your code is formatted before submitting:

```bash
pnpm run format
pnpm run lint
```

## 🚀 Pull Request Process

1. **Fork the Repo**: Create your own fork and work on a feature branch.
2. **Commit Messages**: Follow standard [Conventional Commits](https://www.conventionalcommits.org/).
3. **Documentation**: If you change the architecture or add a feature, update `ARCHITECTURE.md` or `README.md` accordingly.
4. **Self-Review**: Ensure your changes don't break the "Node-only" portability.

**Bad:**

```typescript
const doc = await this.docs.loadDoc(docId);
return doc;
```

### Comments

- Comment **why**, not what
- Keep comments up-to-date with code
- Remove commented-out code before submitting PR

**Good:**

```typescript
// Filter to only project dependencies to reduce search result noise
const entries = await this.docs.getDocEntries(query, packageNames);
```

**Bad:**

```typescript
// Get doc entries
const entries = await this.docs.getDocEntries(query, packageNames);
// const oldEntries = await this.docs.getAllEntries();
```

## File Structure

```dir
src/
├── db/           # Database operations (SQLite)
├── docs/         # Documentation retrieval and ingestion
├── mcp/          # MCP protocol handler
├── project/      # Project context management
├── tools/        # MCP tool implementations
└── types/        # TypeScript type definitions
```

When adding new features:

- Put MCP integrations in `tools/`
- Add types in `types/`
- Add new services in `src/mcp/mcp.service.ts`
- Add tests in  `/feature-name.service.spec.ts`
- You can create additional folders  or files if needed , but cleary specify why it's need in the PR
## Testing

I shall expanding test coverage in future. New features should include tests.

```bash
pnpm test                    # Run all tests
pnpm test -- --watch       # Run in watch mode
pnpm test -- --coverage    # Generate coverage report
```

### Writing Tests Example

```typescript
import { Test, TestingModule } from '@nestjs/testing';
import { SearchTool } from './search.tool';
import { DocsService } from '../docs/docs.service';
import { ProjectService } from '../project/project.service';

describe('SearchTool', () => {
  let tool: SearchTool;
  let docsService: DocsService;
  let projectService: ProjectService;

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      providers: [
        SearchTool,
        {
          provide: DocsService,
          useValue: {
            getDocEntries: jest.fn(),
          },
        },
        {
          provide: ProjectService,
          useValue: {
            getDeps: jest.fn(),
          },
        },
      ],
    }).compile();

    tool = module.get<SearchTool>(SearchTool);
    docsService = module.get<DocsService>(DocsService);
    projectService = module.get<ProjectService>(ProjectService);
  });

  it('should be defined', () => {
    expect(tool).toBeDefined();
  });

  it('should return search results with scores', async () => {
    const mockEntries = [
      {
        id: 'react/hooks',
        title: 'React Hooks',
        keywords: 'useeffect usestate',
        slug: 'hooks',
        package_name: 'react',
        source_path: '/data/react/18.2.0',
      },
      {
        id: 'react/components',
        title: 'React Components',
        keywords: 'props state',
        slug: 'components',
        package_name: 'react',
        source_path: '/data/react/18.2.0',
      },
    ];

    (docsService.getDocEntries as jest.Mock).mockResolvedValue(mockEntries);

    const results = await tool.execute({ query: 'hooks', limit: 5 });

    expect(results.length).toBeGreaterThan(0);
    expect(results[0]).toMatchObject({
      id: 'react/hooks',
      title: 'React Hooks',
      source: 'react',
      type: 'Entry',
    });
    expect(results[0].score).toBeGreaterThan(0.3);
  });

  it('should boost results based on project context', async () => {
    const mockEntries = [
      {
        id: 'node/fs',
        title: 'FileSystem',
        keywords: 'read write',
        slug: 'fs',
        package_name: 'node',
        source_path: '/data/node/20',
      },
    ];

    (docsService.getDocEntries as jest.Mock).mockResolvedValue(mockEntries);
    (projectService.getDeps as jest.Mock).mockResolvedValue({ node: '20' });

    const resultsWithoutContext = await tool.execute({ query: 'fs' });
    const resultsWithContext = await tool.execute({ query: 'fs', projectId: 'my-project' });

    expect(resultsWithContext[0].score).toBeGreaterThan(resultsWithoutContext[0].score);
  });
});
```

## Submitting Changes

### 1. Make Your Changes

```bash
# Edit files
pnpm run format
pnpm run lint
pnpm test
pnpm run build
```

### 2. Commit with Descriptive Messages

```bash
git add src/...
git commit -m "feat: add fuzzy search scoring improvement

- Add keyword boosting for exact term matches
- Add unit tests for scoring algorithm"
```

Use conventional commits:

- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation
- `test:` - Tests
- `refactor:` - Code refactoring
- `perf:` - Performance improvement
- `chore:` - Build, dependencies, tooling

### 3. Push and Create PR

```bash
git push origin feature/your-feature-name
```

Then create a Pull Request on GitHub with:

- Clear title (e.g., "Add fuzzy search scoring")
- Description of what changed and why
- Link to related issues
- Error logs if applicable

### PR Template

```markdown
## What does this PR do?
Brief description of changes.

## Why?
Explanation of the problem being solved or feature being added.

## Related Issues
Closes #123

## Testing
How to test this change.

## Checklist
- [ ] Code follows style guidelines
- [ ] Formatted with Prettier: `pnpm run format`
- [ ] Passes linting: `pnpm run lint`
- [ ] Tests pass: `pnpm test`
- [ ] Builds successfully: `pnpm run build`
- [ ] Updated docs if needed
```

## Common Tasks

### Adding a New Tool

1. Create `src/tools/my-tool.ts`:

```typescript
import { Injectable } from '@nestjs/common';

export interface MyToolInput {
  query: string;
}

@Injectable()
export class MyTool {
  async execute(input: MyToolInput) {
    // Implementation
    return { result: 'success' };
  }
}
```

1. Add to `src/mcp/mcp.service.ts`:

```typescript
private setupTools() {
  // ... existing tools ...
  
  this.server.registerTool(
    'my_tool',
    {
      description: 'What this tool does',
      inputSchema: z.object({
        query: z.string().describe('Search query'),
      })
    },
    async (args) => {
      const result = await this.myTool.execute(args);
      return {
        content: [{ type: 'text', text: JSON.stringify(result) }],
      };
    }
  );
}
```

1. Add to `McpModule` providers in `src/mcp/mcp.module.ts`

2. Write tests in `src/tools/__tests__/my-tool.spec.ts`

### Updating Documentation

Edit markdown files in root directory:

- `README.md` - Main overview
- `ARCHITECTURE.md` - Technical architecture
- `CONTRIBUTING.md` - This file

### Fixing a Bug

1. Create an issue describing the bug
2. Create a test that reproduces it
3. Fix the bug
4. Verify the test now passes
5. Submit PR referencing the issue

## Performance Considerations

- Use database queries efficiently (avoid N+1 queries)
- Cache frequently accessed data
- Implement pagination for large result sets
- Profile performance-critical paths

## Security

- Validate all user inputs
- Sanitize file paths to prevent directory traversal
- Don't log sensitive information
- Keep dependencies updated

## Documentation

Every public function/class should have JSDoc comments:

```typescript
/**
 * Search documentation entries by query string
 * 
 * @param query The search query (e.g., "react hooks")
 * @param limit Maximum number of results to return
 * @param projectId Optional project ID for context filtering
 * @returns Array of matching documentation entries sorted by relevance
 * @throws Error if search fails
 */
async search(
  query: string,
  limit?: number,
  projectId?: string
): Promise<SearchResult[]> {
  // Implementation
}
```

## Releases

Releases follow semantic versioning (MAJOR.MINOR.PATCH):

- MAJOR: Breaking changes
- MINOR: New features (backward compatible)
- PATCH: Bug fixes

## Support & Questions

- 💬 Open an issue to ask questions
- 💡 Discuss ideas in GitHub Discussions
- 📖 Check these first in the following order  
    1. [README.md](README.md)
    2. [ARCHITECTURE.md](ARCHITECTURE.md) 
    3. [Issues](https://github.com/madhan-g-p/DevDocs-MCP/issues)
    4. [Pull Requests](https://github.com/madhan-g-p/DevDocs-MCP/pulls)

## What This Project is Looking For

- Bug fixes and performance improvements
- Documentation improvements
- New documentation source integrations
- Better error messages
- Unit tests
- Better fuzzy search scoring
- Support for additional package ecosystems

## What I am not planning to implement in this project

- Changes that make this a web scraper
- Changes that circumvent [DevDocs.io's](https://github.com/freeCodeCamp/devdocs) [Copyright](https://github.com/freeCodeCamp/devdocs/blob/main/COPYRIGHT)  or [License](https://github.com/freeCodeCamp/devdocs?tab=MPL-2.0-1-ov-file)
- Hardcoded API keys or credentials
- Massive changes without prior discussion

**_Reason:_** Implementing any of the above changes or related code modifications would effectively turn this project into a web scraper, which is not its intended purpose. This project is designed to provide a standardized intermediate format for web development documentation that AI agents can understand. Its goal is to serve as a conceptual framework for internal project documentation, following a structure similar to DevDocs, and to improve communication with AI agents rather than scrape content from external sources.

---

**_Thanks for contributing! 🎉_**

Let me know if you have any questions by opening an issue.