124 lines
3.4 KiB
Markdown
124 lines
3.4 KiB
Markdown
# Honcho MCP Server
|
|
|
|
A Cloudflare Worker that implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for [Honcho](https://honcho.dev), providing AI memory and personalization tools to LLM clients like Claude Desktop.
|
|
|
|
## Quickstart: Use the Hosted Server
|
|
|
|
1. Get an API key at <https://app.honcho.dev>
|
|
2. Add Honcho to your Claude Desktop config:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"honcho": {
|
|
"command": "bunx",
|
|
"args": [
|
|
"mcp-remote",
|
|
"https://mcp.honcho.dev",
|
|
"--header",
|
|
"Authorization:${AUTH_HEADER}"
|
|
],
|
|
"env": {
|
|
"AUTH_HEADER": "Bearer <your-honcho-key>"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Optional Headers
|
|
|
|
| Header | Default | Description |
|
|
| --- | --- | --- |
|
|
| `X-Honcho-Workspace-ID` | `"default"` | Workspace to operate in |
|
|
|
|
## Available Tools
|
|
|
|
**Workspace:** `inspect_workspace` (aggregates metadata, configuration, and peer/session IDs), `list_workspaces` (enumerates accessible workspaces), `search` (semantic search scoped by optional peer/session params), `get_metadata`, `set_metadata`
|
|
|
|
**Peers:** `create_peer`, `list_peers`, `chat`, `get_peer_card`, `set_peer_card`, `get_peer_context`, `get_representation`
|
|
|
|
**Sessions:** `create_session`, `list_sessions`, `delete_session`, `clone_session`, `add_peers_to_session`, `remove_peers_from_session`, `get_session_peers`, `inspect_session`, `add_messages_to_session`, `get_session_messages`, `get_session_message`, `get_session_context`
|
|
|
|
**Conclusions:** `list_conclusions`, `query_conclusions`, `create_conclusions`, `delete_conclusion`
|
|
|
|
**System:** `schedule_dream`, `get_queue_status`
|
|
|
|
## Architecture
|
|
|
|
```
|
|
src/
|
|
index.ts # Worker entry point — parse config, delegate to MCP handler
|
|
server.ts # createServer() — registers all tools on an McpServer
|
|
config.ts # HonchoConfig, parseConfig(), createClient()
|
|
types.ts # ToolContext, result helpers
|
|
tools/
|
|
workspace.ts # inspect, list, search, metadata
|
|
peers.ts # CRUD, chat, card, context, representation
|
|
sessions.ts # CRUD, peers, messages, inspect, context, clone
|
|
conclusions.ts # list, query, create, delete
|
|
system.ts # dream, queue status
|
|
```
|
|
|
|
Built on:
|
|
|
|
- **[agents](https://www.npmjs.com/package/agents)** — `createMcpHandler` for Cloudflare Workers
|
|
- **[@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk)** — `McpServer` for tool registration
|
|
- **[@honcho-ai/sdk](https://www.npmjs.com/package/@honcho-ai/sdk)** v2 — Honcho TypeScript SDK
|
|
|
|
## Self-Hosted Honcho
|
|
|
|
If you run Honcho yourself (for privacy, latency, or offline use), deploy the
|
|
MCP Worker alongside your instance and set `HONCHO_API_URL` in its
|
|
environment.
|
|
|
|
**Local dev (`bun run dev`):** create `mcp/.dev.vars`:
|
|
|
|
```
|
|
HONCHO_API_URL=http://127.0.0.1:28000
|
|
```
|
|
|
|
**Deployed Worker:**
|
|
|
|
```bash
|
|
wrangler secret put HONCHO_API_URL
|
|
# paste your URL when prompted
|
|
```
|
|
|
|
When `HONCHO_API_URL` is unset the Worker routes to `https://api.honcho.dev`,
|
|
so this change is backward-compatible.
|
|
|
|
## Development
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
bun install
|
|
```
|
|
|
|
### Local dev
|
|
|
|
```bash
|
|
bun dev
|
|
```
|
|
|
|
### Type-check
|
|
|
|
```bash
|
|
bun run tsc --noEmit
|
|
```
|
|
|
|
### Test locally
|
|
|
|
```bash
|
|
bunx mcp-remote http://localhost:8787 \
|
|
--header "Authorization:Bearer <key>"
|
|
```
|
|
|
|
### Deploy
|
|
|
|
```bash
|
|
bun run deploy # production
|
|
bun run deploy:staging # staging
|
|
```
|