# woody-mcp

mcp-name: io.github.Gunsmith-Academy/woody-mcp

MCP server for [Woody](https://gunsmith.academy), an AI firearms expert with a verified knowledge base, jurisdiction-specific legal engine, and multi-agent specialist routing.

Add Woody as a native tool in Claude Desktop, Claude Code, Cursor, Windsurf, or any MCP-compatible client.

## What Woody can do

- Answer any firearms question with verified citations (builds, maintenance, legal, ballistics, product specs)
- Look up state-specific firearms laws with jurisdiction-aware citations
- Search a curated knowledge base of manufacturer specs and community-verified data
- Route complex questions to specialist agents (legal, ballistics, maintenance)

## Install

```bash
pip install woody-mcp
```

Or with `uvx` (no install needed):

```bash
uvx woody-mcp
```

## Get an API key

Email [gsa@gunsmith.academy](mailto:gsa@gunsmith.academy) to request a `wdy_` API key.

Tiers:
- **kb_only** — Free. KB search only, no AI answers.
- **standard** — $9/mo. Full AI answers, 30 req/min.
- **premium** — $29/mo. AI answers + Ballistic Solver + legal engine, 60 req/min.

## Claude Desktop setup

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "woody": {
      "command": "woody-mcp",
      "env": {
        "WOODY_API_KEY": "wdy_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. Woody's tools will appear automatically.

## Claude Code setup

```bash
claude mcp add woody -- woody-mcp
```

Then set your key in your shell environment:

```bash
export WOODY_API_KEY=wdy_your_key_here
```

## Tools

### `ask_woody`
Ask Woody any firearms question. Returns an expert answer with citations and legal disclaimers where applicable.

```
question: str        — The firearms question (max 2000 chars)
state: str           — US state code for legal questions (e.g. "TX")
user_tier: str       — matches your API key tier: "free" (kb_only key),
                       "operator" (standard key), or "patriot"/"armorer" (premium key)
```

### `search_knowledge_base`
Search Woody's verified KB directly. Pure vector retrieval, no AI inference, near-zero latency.

```
query: str    — Search query
top_k: int    — Number of results (1-10, default 3)
```

### `check_woody_status`
Check Woody's current capabilities and KB version. No API key required.

## Resources

- `woody://capabilities` — Full tool manifest with input schemas
- `woody://supported-calibers` — List of calibers Woody can analyze

## License

MIT for the MCP client. The Woody API is proprietary.