# Contributing to cve-mcp

Thank you for your interest in contributing to **cve-mcp** -- a 23-tool CVE and vulnerability intelligence MCP server that unifies NVD, EPSS, CISA KEV, GitHub Advisory, and OSV into a single interface for AI agents.

Whether you are fixing a bug, adding a new data source, or improving documentation, your contributions are welcome.

---

## Getting Started

1. **Fork and clone** the repository:

```bash
git clone https://github.com/<your-username>/cve-mcp.git
cd cve-mcp
```

2. **Install dependencies** (Bun 1.3.9+ required):

```bash
bun install
```

3. **Run in dev mode:**

```bash
bun run dev
```

4. **Verify the setup:**

```bash
bun run src/index.ts --list    # Should print all 23 tools
bun run src/index.ts --help    # Show CLI usage
```

### Optional environment variables

```bash
export NVD_API_KEY=your-nvd-api-key       # Raises NVD rate limit (5 -> 50 req/30s)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx     # Raises GHSA rate limit (60 -> 5000 req/hr)
```

---

## Project Structure

```
src/
├── index.ts                 Entry point + CLI
├── types/                   Shared TypeScript types (ToolDef, ToolContext, etc.)
├── protocol/
│   ├── tools.ts             All 23 tool definitions (Zod schemas)
│   └── mcp-server.ts        MCP server + stdio transport
├── nvd/                     NVD API v2 provider (search, get, recent, CPE)
├── epss/                    EPSS exploitation probability provider
├── kev/                     CISA KEV catalog provider (cached)
├── ghsa/                    GitHub Advisory Database provider
├── osv/                     OSV vulnerability provider (single + batch)
├── exploit/                 PoC exploit search via GitHub repositories
├── cwe/                     CWE weakness lookup (40+ embedded entries)
├── cvss/                    CVSS v3.1 vector parser + score calculator
├── meta/                    Meta tools (enrich, prioritize, trending, compare, report)
└── utils/
    ├── rate-limiter.ts      Queue-based rate limiter (NVD compliance)
    └── cache.ts             TTL cache for NVD results and KEV catalog
```

Each data source lives in its own directory under `src/`. Meta tools in `src/meta/` orchestrate queries across multiple providers.

---

## Adding a New Data Source

1. **Create a provider directory** under `src/`:

```
src/your-source/
└── index.ts
```

2. **Implement tools** using the `ToolDef` pattern. Each tool is an object with a Zod schema and a handler function:

```typescript
import { z } from "zod";
import type { ToolDef, ToolContext } from "../types/index.js";

export const yourSourceSearch: ToolDef = {
  name: "your_source_search",
  description: "Search your data source by keyword",
  schema: z.object({
    query: z.string().describe("Search query"),
    limit: z.number().optional().default(10).describe("Maximum results to return"),
  }),
  handler: async (args, context: ToolContext) => {
    // Implementation here
  },
};
```

3. **Register tools** in `src/protocol/tools.ts` by importing and adding them to the tools array.

4. **Follow existing conventions:**
   - Use native `fetch()` for HTTP API calls
   - Add `.describe()` to every Zod schema field
   - Handle API keys as optional (graceful fallback when missing)
   - Respect upstream rate limits

---

## Code Style

- **TypeScript strict mode** -- no `any` types unless absolutely necessary
- **Zod schemas** for all tool input validation
- **`.describe()`** on every schema field (required for MCP tool descriptions)
- **English** for all code, comments, and documentation
- **Import paths** use `.js` extension (ESM resolution)
- **2 spaces** for indentation
- **No unnecessary dependencies** -- the project has only 2 runtime dependencies by design

---

## Submitting Changes

1. **Fork** the repository on GitHub.
2. **Create a feature branch** from `main`:

```bash
git checkout -b feat/your-feature-name
```

3. **Make your changes** and verify they work:

```bash
bun run src/index.ts --list          # Ensure tools register correctly
bun run src/index.ts --tool <name> '{"arg": "value"}'   # Test your tool
```

4. **Commit** using [Conventional Commits](https://www.conventionalcommits.org/) format:

```bash
git commit -m "feat: add new-source provider with search tool"
git commit -m "fix: handle empty NVD response for withdrawn CVEs"
```

5. **Push** to your fork and **open a Pull Request** against `main`.

6. In your PR description, include:
   - What the change does
   - How to test it
   - Any new environment variables or dependencies (if applicable)

---

## Reporting Bugs

Please use [GitHub Issues](https://github.com/badchars/cve-mcp/issues) to report bugs. Include:

- **Description** of the problem
- **Steps to reproduce** (tool name, input arguments, expected vs actual output)
- **Environment** (OS, Bun version, Node version if applicable)
- **Error output** (full error message or stack trace)

If you find a security vulnerability, please follow the [Security Policy](SECURITY.md) instead of opening a public issue.

---

## License

By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).