# openwifi-mcp

Three MCP servers that turn Claude Code into an interactive OpenWiFi
triage assistant. When registered in your project's `.mcp.json`, Claude
gains native tools to search the linux-wireless patch mirror, look up
Jira tickets, run the LLM triage pipeline, dry-run + apply upstream
backports, and drive OpenWiFi builds — all from within the same
conversation you're already having about a bug.

Nothing runs in the cloud. All state lives on your machine or the
build host you already control.

## What ships

| Server | Purpose | Backing service |
|---|---|---|
| `openwifi-jira`    | Read-only Jira ticket lookup + similar-ticket search | [openwifi-ticket-index](https://github.com/firasshaari/openwifi-ticket-index) |
| `openwifi-patches` | linux-wireless FTS5 search + LLM triage + backport helpers | [openwifi-kernel-patches](https://github.com/firasshaari/openwifi-kernel-patches) |
| `openwifi-build`   | `make build/status/tail/fetch/deploy` wrappers over SSH | Your OpenWiFi build project |

All three are stdio-transport MCP servers written in Python with FastMCP.

## Tools exposed

**openwifi-jira** (read-only):
- `jira_list_releases` — synced Jira fixVersions with ticket counts
- `jira_search_tickets(q, fix_version?, status?, assignee?, limit?)` — full-text search
- `jira_get_ticket(key)` — full ticket incl. comments, attachments, changelog, cross-refs
- `jira_get_attachment_text(id)` — text content of indexed attachments
- `jira_ticket_similar(anchor, limit?)` — similar tickets by key or symptom

**openwifi-patches**:
- `patches_stats` — DB stats + LLM availability
- `patches_search(q, subject_prefix?, author?, since?, until?, limit?)`
- `patches_get(message_id)` — raw RFC 5322 body
- `patches_expand_query(symptom)` — LLM-generated FTS5 query preview
- `patches_triage(symptom | ticket, top_n?)` — full pipeline (patches + LLM explanations + similar tickets)
- `patches_dry_run_backport(message_id, tree)` — non-mutating apply check
- `patches_apply_backport(message_id, tree)` — **MUTATING** — commits to the tree

**openwifi-build** — wraps your Claude-OpenWiFi `make` targets:
- `build_help`, `build_status`, `build_tail(tag, lines?)`, `build_fetch(tag)` (non-mutating)
- `build_start(branch, target, pr?)` — **MUTATING** — kicks off a long-running build
- `build_deploy(tag, ap, confirm=False)` — **MUTATING** — sysupgrades a real AP

## Install

```bash
git clone https://github.com/YOU/openwifi-mcp.git
cd openwifi-mcp
./setup.sh
```

The setup creates a venv, installs the package editable, and writes
`.mcp.snippet.json` you can drop into your project's `.mcp.json` (or
`~/.claude.json` for user-scoped access).

Point three env vars at your existing services:

```bash
TICKET_INDEX_URL    = http://<host>:20504   # openwifi-ticket-index
PATCH_SEARCH_URL    = http://<host>:20503   # openwifi-kernel-patches
CLAUDE_OPENWIFI_ROOT = /abs/path/to/Claude-OpenWiFi
```

Restart Claude Code and the tools appear in every session under that
project.

## Suggested permission allowlist

Add to your project's `.claude/settings.json` so read-only tools skip
the confirmation prompt but mutating tools still require it:

```json
{
  "permissions": {
    "allow": [
      "mcp__openwifi-jira__*",
      "mcp__openwifi-patches__patches_stats",
      "mcp__openwifi-patches__patches_search",
      "mcp__openwifi-patches__patches_get",
      "mcp__openwifi-patches__patches_expand_query",
      "mcp__openwifi-patches__patches_triage",
      "mcp__openwifi-patches__patches_dry_run_backport",
      "mcp__openwifi-build__build_help",
      "mcp__openwifi-build__build_status",
      "mcp__openwifi-build__build_tail",
      "mcp__openwifi-build__build_fetch"
    ]
  }
}
```

`patches_apply_backport`, `build_start`, and `build_deploy` are
deliberately NOT allowlisted — they mutate real state and should always
prompt.

## Slash command / skill

Pair with a skill like this in `.claude/skills/openwifi-triage/SKILL.md`
so the user can just type `/openwifi-triage WIFI-15461` (see the
[example in Claude-OpenWiFi](../Claude-OpenWiFi/.claude/skills/openwifi-triage/SKILL.md)).

## License

MIT. See [LICENSE](LICENSE).