WWN-MCP

Wawona MCP — a local-embeddings RAG + stdio Model Context Protocol server that gives any MCP-capable agent retrieval-backed knowledge of the Wawona stack: Wayland / Smithay / Weston / Niri, Apple + Android UI ladders, Vulkan/OpenGL paths, App Store / Play compliance, and the wwn-* patched-software repos. WWN = Wawona.

This is not mcp-nixos. The host contract is the same idea (the agent host spawns a PATH binary over stdio), but the corpus, tools, and package are Wawona-only. There is no public URL / Streamable HTTP transport (mcp.wawona.io was never shipped — do not use it).

Works with any MCP host that can spawn a stdio server (Cursor, VS Code, Claude Desktop, Windsurf, Antigravity, Zed, custom agents, …). Cursor is one client — not the only one. Zed uses context_servers instead of mcpServers (see docs/usage.md).

Install a PATH binary for MCP hosts — do not wire nix run --refresh into editor config (Zed’s ~60s initialize timeout → “Context server request timeout”).

Quick start

# Install once (recommended for Cursor / Zed / …)
nix profile install github:Wawona/WWN-MCP

# Terminal smoke (prints JSON / search hits and exits)
wwn-mcp info
wwn-mcp search "watchOS GPU"
# or: nix run github:Wawona/WWN-MCP#wwn-mcp -- info

# Bare `wwn-mcp` / `nix run …#wwn-mcp` on an interactive terminal prints MCP
# host setup help (Cursor + Zed examples) and exits. Your agent must spawn
# the process with piped stdin for the MCP server.

Cursor / VS Code–shaped hosts (mcpServers)

{
  "mcpServers": {
    "wwn-mcp": { "command": "wwn-mcp", "args": [] }
  }
}

Zed (context_servers in ~/.config/zed/settings.json)

Use an absolute path (Dock-launched Zed has no shell PATH):

{
  "context_servers": {
    "wwn-mcp": {
      "command": "/Users/YOU/.nix-profile/bin/wwn-mcp",
      "args": [],
      "env": {}
    }
  }
}

Without Nix:

pip install -e ".[all]"
wwn-mcp index --knowledge
wwn-mcp info

With home-manager / dendritic:

programs.wwn-mcp.enable = true;

See docs/deployment.md. On first empty DB, serve auto-indexes shipped knowledge/ in the background so initialize is not blocked. For local sibling repos: wwn-mcp index --local-siblings (or fetch then index).

Related MCP server: Contextual MCP Server

Documentation

All documentation lives in docs/:

• Overview & architecture

• Corpus catalog

• MCP tools & resources

• Deployment (home-manager / dendritic stdio)

• Usage (MCP host wiring + local dev)

• Contributing

License

MIT — see LICENSE. Open source. Third-party documentation and source that WWN-MCP indexes are fetched at runtime and are never vendored into this repository; their license notices are surfaced in result citations.