# expert-mcp-server

MCP server for [expert-service](https://github.com/benthomasson/expert-service) knowledge bases. Lets any MCP-compatible agent query beliefs, search documents, and explore reasoning chains.

## Install

```bash
uv tool install git+https://github.com/benthomasson/expert-mcp-server
```

## Configure

Create a `.expert.toml` in your project root:

```toml
url = "https://expert.ftl2.com"
project = "your-project-name"
api_key = "your-api-key"
```

Or set environment variables: `EXPERT_URL`, `EXPERT_API_KEY`, `EXPERT_PROJECT`.

Global config can also go in `~/.config/expert/config.toml` under `[default]`.

## Usage

### Claude Code

```bash
claude mcp add expert-service -- expert-mcp-server
```

### Claude Desktop / other MCP clients

Add to your MCP config:

```json
{
  "mcpServers": {
    "expert-service": {
      "command": "expert-mcp-server"
    }
  }
}
```

Or run from source:

```json
{
  "mcpServers": {
    "expert-service": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/benthomasson/expert-mcp-server", "expert-mcp-server"]
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `deep_search` | Dual-path retrieval across beliefs and source documents with IDF ranking. Sub-second, no LLM call. **Start here.** |
| `ask` | LLM-synthesized answer grounded in the knowledge base. |
| `search` | Full-text search across beliefs, entries, and source documents. |
| `explain_belief` | Trace why a belief is IN or OUT through its justification chain. |
| `what_if` | Simulate retracting or asserting a belief to see the cascade. |
| `get_belief` | Full details for a specific belief including justifications. |
| `list_beliefs` | List beliefs filtered by status (IN/OUT). |
| `list_projects` | List available expert knowledge bases. |
| `list_entries` | List analysis entries (reports, findings). |
| `get_entry` | Read the full content of an entry. |

All tools accept an optional `project` parameter. If omitted, the default project from config is used.

## License

MIT