<p align="center">
  <img src="https://24klabs.ai/logo.png" alt="24K Labs" width="120" />
</p>

<h1 align="center">24K Labs MCP Server</h1>

<p align="center">
  <strong>AI code analysis tools that plug into Claude Code, Cursor, VS Code, and any MCP client.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/24klabs-mcp/"><img src="https://img.shields.io/pypi/v/24klabs-mcp?color=gold&label=PyPI" alt="PyPI" /></a>
  <a href="https://www.npmjs.com/package/@24klabs/mcp-server"><img src="https://img.shields.io/npm/v/@24klabs/mcp-server?color=gold&label=npm" alt="npm" /></a>
  <a href="https://github.com/Haustorium12/24klabs-mcp"><img src="https://img.shields.io/github/stars/Haustorium12/24klabs-mcp?style=social" alt="GitHub Stars" /></a>
  <a href="https://github.com/Haustorium12/24klabs-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License" /></a>
  <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.10+-blue" alt="Python 3.10+" /></a>
</p>

<p align="center">
  6 professional code analysis tools powered by Claude (Haiku / Sonnet / Opus).<br/>
  Pay per request via <a href="https://www.x402.org/">x402</a> or Stripe (coming soon). Free dev mode included.
</p>

---

## What is this?

24K Labs MCP Server gives any AI assistant access to **six specialized code analysis tools** through the [Model Context Protocol](https://modelcontextprotocol.io/). Each tool calls the 24K Labs API, which routes your request to the right Claude model for the job -- Haiku for speed, Sonnet for depth, Opus for the hard stuff.

It works anywhere MCP works:

- **Claude Code** (CLI)
- **Cursor**
- **VS Code** (via Copilot Chat MCP support)
- **Any MCP-compatible client**

One `pip install`. One config block. Six tools ready to go.

---

## Features

- **`explain_code`** -- Get a clear, structured breakdown of what any code does. Powered by Claude Haiku.
- **`debug_assist`** -- Paste buggy code and an error message. Get the root cause, severity, and a fix. Powered by Claude Sonnet.
- **`code_review`** -- Full code review covering security, performance, and architecture with a quality score. Powered by Claude Sonnet.
- **`security_audit`** -- OWASP-based vulnerability assessment with CVSS scores and remediation steps. Powered by Claude Opus.
- **`automation_script`** -- Describe what you need in plain English, get a complete working script. Powered by Claude Sonnet.
- **`mcp_blueprint`** -- Design a complete MCP server architecture with tools, schemas, and deployment guide. Powered by Claude Opus.

Every tool supports three analysis tiers (`quick`, `standard`, `pro`) so you control depth and cost.

---

## Quick Start

### Install

```bash
pip install 24klabs-mcp
```

Or install from source:

```bash
git clone https://github.com/Haustorium12/24klabs-mcp.git
cd 24klabs-mcp
pip install -e .
```

### Configure in Claude Code

Add to your project's `.mcp.json` (or `~/.claude/.mcp.json` for global):

```json
{
  "mcpServers": {
    "24klabs": {
      "command": "python",
      "args": ["-m", "server"],
      "cwd": "/path/to/24klabs-mcp",
      "env": {
        "TWENTYFOURK_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Configure in Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "24klabs": {
      "command": "python",
      "args": ["/path/to/24klabs-mcp/server.py"],
      "env": {
        "TWENTYFOURK_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Configure in VS Code

Add to your VS Code `settings.json`:

```json
{
  "mcpServers": {
    "24klabs": {
      "command": "python",
      "args": ["/path/to/24klabs-mcp/server.py"],
      "env": {
        "TWENTYFOURK_API_KEY": "your-api-key"
      }
    }
  }
}
```

That's it. Your AI assistant now has six new tools.

---

## Tool Reference

### `explain_code`

> Get a clear, structured explanation of what code does.

| Detail | Value |
|--------|-------|
| **Model** | Claude Haiku |
| **Price** | $0.01 / quick -- $0.02 / standard -- $0.05 / pro |

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `code` | `string` | Yes | The code to explain |
| `language` | `string` | No | Programming language (auto-detected if omitted) |
| `context` | `string` | No | Additional context about the code |
| `tier` | `string` | No | `quick`, `standard` (default), or `pro` |

**Example usage in Claude Code:**

```
> Use explain_code to explain this Python function:

def memoize(func):
    cache = {}
    def wrapper(*args):
        if args not in cache:
            cache[args] = func(*args)
        return cache[args]
    return wrapper
```

**Example output (abbreviated):**

```
This is a memoization decorator that caches function results.

Purpose: Avoids redundant computation by storing previously computed
results in a dictionary keyed by the function arguments.

How it works:
1. Creates a closure with a `cache` dict
2. On each call, checks if args are already cached
3. If not cached, calls the original function and stores the result
4. Returns the cached result

Edge cases to watch:
- Only works with hashable arguments (no lists/dicts as args)
- Cache grows unbounded -- no eviction policy
- Not thread-safe
```

---

### `debug_assist`

> Find bugs, explain errors, and suggest fixes.

| Detail | Value |
|--------|-------|
| **Model** | Claude Sonnet |
| **Price** | $0.02 / quick -- $0.05 / standard -- $0.10 / pro |

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `code` | `string` | Yes | The buggy code or code that throws an error |
| `error_message` | `string` | No | The error message or traceback |
| `language` | `string` | No | Programming language (auto-detected if omitted) |
| `tier` | `string` | No | `quick`, `standard` (default), or `pro` |

**Example usage in Claude Code:**

```
> Use debug_assist to find the bug in this code. The error is "TypeError: unhashable type: 'list'"

def count_items(items):
    seen = {}
    for item in items:
        seen[item] = seen.get(item, 0) + 1
    return seen

count_items([[1, 2], [3, 4], [1, 2]])
```

---

### `code_review`

> Comprehensive code review covering security, performance, and architecture.

| Detail | Value |
|--------|-------|
| **Model** | Claude Sonnet |
| **Price** | $0.02 / quick -- $0.05 / standard -- $0.10 / pro |

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `code` | `string` | Yes | The code to review |
| `focus` | `string` | No | Specific area to focus on (e.g. `security`, `performance`, `architecture`) |
| `language` | `string` | No | Programming language (auto-detected if omitted) |
| `tier` | `string` | No | `quick`, `standard` (default), or `pro` |

**Example usage in Claude Code:**

```
> Use code_review on my Express.js auth middleware, focus on security
```

---

### `security_audit`

> OWASP-based security vulnerability assessment.

| Detail | Value |
|--------|-------|
| **Model** | Claude Opus |
| **Price** | $0.05 / quick -- $0.10 / standard -- $0.25 / pro |

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `code` | `string` | Yes | The code to audit for security vulnerabilities |
| `context` | `string` | No | Additional context (e.g. `web app`, `API endpoint`, `auth system`) |
| `language` | `string` | No | Programming language (auto-detected if omitted) |
| `tier` | `string` | No | `quick`, `standard` (default), or `pro` |

**Example usage in Claude Code:**

```
> Run security_audit on my login endpoint, context is "Express.js API with JWT auth"
```

**Example output (abbreviated):**

```
SECURITY AUDIT REPORT
=====================
Severity: HIGH

Vulnerabilities Found:
1. [CRITICAL] SQL Injection in user lookup (OWASP A03:2021)
   CVSS: 9.8 -- Line 14: raw string interpolation in query
   Fix: Use parameterized queries

2. [HIGH] Missing rate limiting (OWASP A07:2021)
   CVSS: 7.5 -- No throttle on login attempts
   Fix: Add express-rate-limit middleware

3. [MEDIUM] JWT secret from env without validation
   CVSS: 5.3 -- Falls back to empty string if env var missing
   Fix: Fail hard if JWT_SECRET is not set
```

---

### `automation_script`

> Generate a complete, working automation script from natural language requirements.

| Detail | Value |
|--------|-------|
| **Model** | Claude Sonnet |
| **Price** | $0.02 / quick -- $0.05 / standard -- $0.10 / pro |

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `requirements` | `string` | Yes | What the script should do (natural language) |
| `language` | `string` | No | Target language (default: `python`) |
| `context` | `string` | No | Additional constraints or context |
| `tier` | `string` | No | `quick`, `standard` (default), or `pro` |

**Example usage in Claude Code:**

```
> Use automation_script: "Watch a directory for new CSV files, validate headers match a schema, and upload valid ones to S3"
```

---

### `mcp_blueprint`

> Design a complete MCP server architecture with implementation guide.

| Detail | Value |
|--------|-------|
| **Model** | Claude Opus |
| **Price** | $0.05 / quick -- $0.10 / standard -- $0.25 / pro |

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `requirements` | `string` | Yes | What the MCP server should do (natural language) |
| `language` | `string` | No | Implementation language (default: `python`) |
| `context` | `string` | No | Additional context (e.g. `for Claude Code`, `for Cursor`) |
| `tier` | `string` | No | `quick`, `standard` (default), or `pro` |

**Example usage in Claude Code:**

```
> Use mcp_blueprint: "MCP server that wraps the Stripe API -- tools for creating customers, charges, subscriptions, and listing invoices"
```

---

## Tiers Explained

Every tool accepts a `tier` parameter that controls analysis depth:

| Tier | Depth | Speed | Best For |
|------|-------|-------|----------|
| `quick` | Surface-level scan | ~2-5s | Quick sanity checks, simple questions |
| `standard` | Thorough analysis | ~5-15s | Day-to-day code review and debugging (default) |
| `pro` | Exhaustive deep-dive | ~15-45s | Production releases, security sign-offs, architecture decisions |

The `pro` tier uses more tokens and produces longer, more detailed output. Use it when the stakes are high.

---

## Payment

### How x402 Works

24K Labs uses the [x402 protocol](https://www.x402.org/) for machine-to-machine payments. When a request requires payment, the API returns a `402 Payment Required` response with the price in USDC on Base L2.

### Dev Mode (Free)

By default, the server runs in **dev mode** -- requests pass through without payment so you can test everything. The `X-Payment: dev-mode` header is sent automatically.

To switch to production, set your API key:

```bash
export TWENTYFOURK_API_KEY="your-api-key"
```

### Pricing Table

| Tool | Quick | Standard | Pro |
|------|-------|----------|-----|
| `explain_code` | $0.01 | $0.02 | $0.05 |
| `debug_assist` | $0.02 | $0.05 | $0.10 |
| `code_review` | $0.02 | $0.05 | $0.10 |
| `security_audit` | $0.05 | $0.10 | $0.25 |
| `automation_script` | $0.02 | $0.05 | $0.10 |
| `mcp_blueprint` | $0.05 | $0.10 | $0.25 |

All prices in USDC. Stripe billing coming soon.

---

## Configuration Options

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `TWENTYFOURK_API_KEY` | (none) | Your 24K Labs API key for authenticated/paid requests |
| `TWENTYFOURK_API_URL` | `https://api.24klabs.ai` | API base URL (override for self-hosted or staging) |

---

## Use Cases

### PR Review Automation
Run `code_review` on every pull request to catch security issues, performance regressions, and architectural problems before they reach main.

### Security Audit Before Deploy
Run `security_audit` at `pro` tier on auth endpoints, payment handlers, and data access layers before every production deploy.

### Onboarding to a New Codebase
Use `explain_code` to rapidly understand unfamiliar modules. Paste a file, get a structured breakdown of what it does and why.

### Bug Triage
Paste the stack trace and the failing code into `debug_assist`. Get the root cause, severity, and a fix -- without context-switching to a browser.

### Script Generation
Need a one-off migration script, a data pipeline, or a CI/CD helper? Describe it in English with `automation_script` and get a working script back.

### MCP Server Prototyping
Designing a new MCP integration? Use `mcp_blueprint` to get a full architecture with tool definitions, schemas, implementation code, and a deployment guide.

---

## API Reference

The 24K Labs REST API is fully documented at:

**[https://api.24klabs.ai/docs](https://api.24klabs.ai/docs)**

All six endpoints accept the same base payload:

```json
{
  "code": "string",
  "tier": "quick | standard | pro",
  "context": "string (optional)",
  "language": "string (optional)"
}
```

---

## FAQ

**Do I need an API key to try it?**
No. The server runs in dev mode by default, which sends requests without payment. Set `TWENTYFOURK_API_KEY` when you're ready for production use.

**What models are used?**
`explain_code` uses Claude Haiku for speed. `debug_assist`, `code_review`, and `automation_script` use Claude Sonnet for depth. `security_audit` and `mcp_blueprint` use Claude Opus for the highest quality analysis.

**Is my code sent to a third party?**
Your code is sent to the 24K Labs API (`api.24klabs.ai`), which routes it to Anthropic's Claude API. No code is stored, logged, or used for training. See the [privacy policy](https://24klabs.ai/privacy) for details.

**What languages are supported?**
All of them. The tools auto-detect the programming language from the code you provide. You can also pass `language` explicitly for better results.

**What's the request timeout?**
120 seconds. If your code snippet is very large, consider breaking it into smaller pieces or using the `quick` tier.

---

## Contributing

Contributions are welcome. Here's how:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/your-feature`)
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Please open an issue first for large changes so we can discuss the approach.

---

## License

MIT -- see [LICENSE](LICENSE) for details.

---

## Links

- **Website**: [https://24klabs.ai](https://24klabs.ai)
- **API Docs**: [https://api.24klabs.ai/docs](https://api.24klabs.ai/docs)
- **GitHub**: [https://github.com/Haustorium12/24klabs-mcp](https://github.com/Haustorium12/24klabs-mcp)
- **PyPI**: [https://pypi.org/project/24klabs-mcp/](https://pypi.org/project/24klabs-mcp/)
- **npm**: [https://www.npmjs.com/package/@24klabs/mcp-server](https://www.npmjs.com/package/@24klabs/mcp-server)

---

<p align="center">
  Built by <a href="https://24klabs.ai">24K Labs</a>
</p>