Skip to content

mcp-server.md

Latest commit

 

History

History
72 lines (56 loc) · 3.44 KB

mcp-server.md

File metadata and controls

72 lines (56 loc) · 3.44 KB
description Run OpenHuman Core as a read-only stdio Model Context Protocol server.
icon plug

MCP Server

OpenHuman Core can run as an opt-in stdio MCP server for local MCP clients such as Claude Desktop, Cursor, or Zed.

openhuman-core mcp

The command does not start the HTTP JSON-RPC server. It reads newline-delimited JSON-RPC 2.0 messages from stdin and writes MCP responses to stdout. Logs go to stderr; add --verbose for debug output.

Tools

The MCP surface is deliberately read-only and routes through the existing controller registry plus the core security policy read gate:

MCP tool Backing RPC Purpose
memory.search openhuman.memory_tree_search Keyword search over memory-tree chunks.
memory.recall openhuman.memory_tree_recall Semantic recall over memory-tree summaries/chunks.
tree.read_chunk openhuman.memory_tree_get_chunk Read one chunk returned by search or recall.
tree.browse openhuman.memory_tree_list_chunks Paginated chunk listing with source / entity / time filters.
tree.top_entities openhuman.memory_tree_top_entities Most-referenced canonical entities, optionally filtered by kind.
tree.list_sources openhuman.memory_tree_list_sources Distinct ingest sources with chunk counts and last-activity timestamps.

memory.search and memory.recall accept query plus optional k (default 10, capped at 50). tree.read_chunk accepts chunk_id. tree.browse accepts optional source_kinds, source_ids, entity_ids, since_ms, until_ms, query, k, and offset. tree.top_entities accepts optional kind and k. tree.list_sources accepts an optional user_email_hint.

Tool Registry

The HTTP JSON-RPC server also exposes a read-only global tool registry for agents and dashboards that need discovery metadata without opening an MCP stdio session:

RPC method Purpose
openhuman.tool_registry_list List MCP stdio tools and controller-backed tools with stable tool_id, route, version, input/output schemas, allowed agents, tags, enabled state, and health.
openhuman.tool_registry_get Return one registry entry by tool_id, for example memory.search or tools.web_search.

The registry is discovery-only. It does not change tool dispatch or permission checks; MCP calls still go through tools/call, and controller-backed tools still route through their existing JSON-RPC methods.

Smoke Test

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | openhuman-core mcp

The response should include capabilities.tools from initialize and the curated tool names from tools/list. A successful run writes exactly two compact JSON response lines to stdout; the notifications/initialized message is a notification and has no response.

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"openhuman-core","version":"<crate version>"},"instructions":"..."}}
{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"memory.search",...},{"name":"memory.recall",...},{"name":"tree.read_chunk",...},{"name":"tree.browse",...},{"name":"tree.top_entities",...},{"name":"tree.list_sources",...}]}}