# LobsterMCP

> OpenClaw documentation, queryable by AI agents — so Claude Code stops guessing and starts knowing.

**Author:** Osama · **License:** MIT · *Unofficial community tool, not affiliated with or endorsed by OpenClaw.*

---

## What is this?

[OpenClaw](https://openclaw.ai) is an AI agent platform for connecting LLMs to messaging channels, tools, and services. When Claude Code (or any AI agent) works on an OpenClaw project, it needs to look things up constantly: *How do I configure a model? What's the JSON5 syntax for provider auth? How do I set up multi-agent routing?*

**LobsterMCP** is an MCP server that puts the full OpenClaw documentation directly in front of your agent — 194 entries across 13 topics, indexed with BM25 search. No web lookups, no hallucinations, no asking the user to go find the docs.

---

## Installation

### Option 1 — Claude Code (local build)

```bash
git clone https://github.com/osamac2128/lobstermcp
cd lobstermcp
npm install && npm run build
claude mcp add lobster-mcp -s user -- node /absolute/path/to/lobstermcp/dist/index.js
```

### Option 2 — Claude Code settings.json

```json
{
  "mcpServers": {
    "lobster-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/lobstermcp/dist/index.js"]
    }
  }
}
```

---

## Tools

### `resolve-topic`

Finds the right documentation topic for your query. Call this first.

```
Input:  { query: "models" }

Output: {
  topics: [{
    topicId: "models",
    name: "Models & Model Selection",
    description: "Configuring primary models, fallbacks, allowlists...",
    entryCount: 5,
    confidence: 1.0,
    relatedTopics: ["providers", "configuration", "agents"]
  }]
}
```

### `query-config-docs`

Returns full documentation and code examples for your query.

```
Input:  { query: "set primary model anthropic", topicId: "models" }

Output: Markdown with full docs, config snippets, CLI examples, and source URLs
```

---

## Topics

| Topic ID | Entries | Covers |
|----------|---------|--------|
| `models` | 5 | Primary model, fallbacks, allowlists, aliases, `/model` command |
| `providers` | 18 | Anthropic, OpenAI, OpenRouter, Ollama, GLM, GitHub Copilot, and more |
| `configuration` | 5 | `openclaw.json` config file, JSON5 format, all config keys, `config.patch`/`config.apply` |
| `gateway` | 21 | Running the gateway, remote access, pairing, protocol, multiple gateways, ACP bridge |
| `agents` | 20 | Agent runtime, workspaces, `AGENTS.md`/`SOUL.md`/`TOOLS.md`, multi-agent routing |
| `sessions` | 6 | Session keys, compaction, pruning, session store |
| `tools` | 16 | exec, browser, web search, agent-send, slash commands, llm-task, subagents |
| `skills-plugins` | 10 | Creating skills (`SKILL.md` format), plugin manifest, ClawdHub registry |
| `channels` | 23 | Telegram, Discord, Slack, WhatsApp, Matrix, Signal, iMessage, and more |
| `install` | 23 | Installation, onboarding wizard, Docker, updating, platform guides |
| `concepts` | 23 | Memory, system prompts, context, streaming, queue, retry, usage tracking |
| `security-sandbox` | 11 | Sandboxing, elevated tools, exec approvals, tool policies |
| `debugging` | 13 | `openclaw doctor`, logs, health checks, FAQ, common issues |

**13 topics · 194 documentation entries**

---

## Example queries

```
resolve-topic: "how to configure a model"
→ topicId: "models"

query-config-docs: "set primary model anthropic claude", topicId: "models"
→ Full docs on agents.defaults.model.primary, fallbacks, allowlist config

resolve-topic: "anthropic api key"
→ topicId: "providers"

query-config-docs: "anthropic setup-token auth", topicId: "providers"
→ Full docs on setup-token vs API key, onboarding wizard, config snippet

resolve-topic: "run gateway background"
→ topicId: "gateway"

query-config-docs: "multi-agent routing bindings", topicId: "agents"
→ Full docs on agents.list, bindings, agentId, isolated workspaces
```

---

## Architecture

- **Search** — BM25 in-memory search with Porter stemmer and field boosting (title 3×, tags 2×, description 1.5×)
- **Storage** — Static JSON files loaded at startup, zero runtime dependencies
- **Transport** — MCP stdio transport (works with any MCP-compatible client)
- **Content** — Sourced from official OpenClaw documentation

```
lobstermcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── tools/
│   │   ├── resolve-topic.ts  # Topic resolution tool
│   │   └── query-docs.ts     # Doc search tool
│   ├── search/
│   │   ├── engine.ts         # BM25 search engine
│   │   └── tokenizer.ts      # Porter stemmer tokenizer
│   └── store/
│       ├── index.ts          # DocStore class
│       ├── loader.ts         # Content file loader
│       └── types.ts          # Shared types
├── content/                  # Documentation JSON (13 files + topics.json)
└── scripts/
    └── build-openclaw-content.mjs  # Regenerate content from OpenClaw source
```

---

## Updating the content

Content is generated from the OpenClaw source docs. To regenerate:

```bash
# Requires openclaw source at ../openclaw (relative to this repo)
node scripts/build-openclaw-content.mjs
npm run build
```

---

## Development

```bash
npm install      # Install dependencies
npm run build    # Compile TypeScript
npm run dev      # Watch mode
npm start        # Run server
```

---

## Requirements

- Node.js 18+
- Any MCP-compatible client (Claude Code, Claude Desktop, etc.)

---

## License

MIT — © Osama