HomeMind MCP

MCP server for AI assistants: ArkTS reachability (via ArkAnalyzer) and knowledge-base tools. Published as @homemind/mcp. Requires Node.js 18+.

Full tool API and modules: docs/architecture/mcp-server.md (repo root).

Quick start

From monorepo root:

npm install
npm run build:mcp
npm run dev:mcp
npm run kb:build -- --buildMode sdk -o bundled-sdk-kb --ohosSdkHome $OHOS_SDK_HOME

In this package only:

npm install && npm run dev
# production: npm run build && npm start

Debug with MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Tools

Registered as {module}_{tool}:

| Area | Tools | | --- | --- | | Reachability | reachability_call_graph, reachability_query_path, reachability_impact_analysis, reachability_refactor_plan | | KB | kb_build, kb_query, kb_intent_catalog, kb_qa, kb_merge, kb_error_memory, kb_enrich_categories, kb_wiki_generate, kb_diagrams_generate |

The host exposes tools; the model picks them from descriptions plus your rules/skills (e.g. repo skills/kb for orchestrating kb_*).

Working directory: tools resolve paths from process.cwd() after startup. That should be your ArkTS / OpenHarmony app git root. You can get there in three ways (combine as needed):

1. MCP cwd — set in the client so the server process starts in the app repo (works for per-project configs with a fixed path).
2. HOMEMIND_PROJECT_ROOT — absolute path to the app root; the server chdirs there on startup (CLI and MCP). Use this when the host does not set cwd but can pass environment variables, e.g. Cursor global ~/.cursor/mcp.json with "env": { "HOMEMIND_PROJECT_ROOT": "${workspaceFolder}" } so each workspace becomes the project root without editing paths.
3. Project-local MCP — put MCP config under the app repo (e.g. .cursor/mcp.json, Claude Code .mcp.json) so the team only maintains one layout; many clients default the child process working directory to the opened folder when the config lives in the project.

If neither cwd nor HOMEMIND_PROJECT_ROOT points at your app, reachability and .homemind/ paths will be wrong.

Sessions: reuse a stable sessionId across related kb_* calls when supported. If a tool returns { skipped: true }, change the query instead of retrying. Treat MCP results as evidence for API claims.

Packaging

Published files (see package.json): dist/, schemas/, knowledge/, bundled-sdk-kb/, models/, README.md.

Bundled SDK KB: default resolution uses bundled-sdk-kb/index/kb-index.json when there is no ~/.homemind/sdk-kb.json and no cwd/.homemind/sdk/. Set HOMEMIND_USE_BUNDLED_SDK=0 to disable. If you pass sdkApiVersion to kb_query / kb_qa / kb_intent_catalog, it must match bundled-sdk-kb/manifest.json when the bundle is the active source.

MCP client setup

Prefer cwd or HOMEMIND_PROJECT_ROOT (see above) so the server sees the app root.

JSON hosts (Cursor, Claude Desktop, …)

Fixed path (per machine / per project file):

{
  "mcpServers": {
    "homemind-mcp": {
      "command": "npx",
      "args": ["-y", "@homemind/mcp"],
      "cwd": "/absolute/path/to/your-arkts-project"
    }
  }
}

Cursor: global ~/.cursor/mcp.json — you do not need a hard-coded app path if the client expands variables. Prefer HOMEMIND_PROJECT_ROOT (implemented in this package); add cwd with the same value when your Cursor version expands it there too:

{
  "mcpServers": {
    "homemind-mcp": {
      "command": "npx",
      "args": ["-y", "@homemind/mcp"],
      "cwd": "${workspaceFolder}",
      "env": {
        "HOMEMIND_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

After spawn, process.cwd() should match the open workspace (cwd and/or startup chdir from HOMEMIND_PROJECT_ROOT). If your client does not expand cwd, use env only:

"homemind-mcp": {
  "command": "npx",
  "args": ["-y", "@homemind/mcp"],
  "env": { "HOMEMIND_PROJECT_ROOT": "${workspaceFolder}" }
}

Claude Desktop: claude_desktop_config.json — macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\, Linux ~/.config/Claude/. Restart the app after edits.

Claude Code: same shape in project .mcp.json; example: tests/fixtures/claude-code-config.example.json. CLI: claude mcp add --transport stdio homemind-mcp -- npx -y @homemind/mcp (-- after the server name).

Codegenie

~/.config/codegenie/codegenie.jsonc (or project .codegenie/codegenie.jsonc / codegenie.jsonc):

{
  "mcp": {
    "homemind-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@homemind/mcp"],
      "enabled": true
    }
  }
}

Or codegenie mcp add → name homemind-mcp, command npx -y @homemind/mcp. Verify: codegenie mcp list.

OpenAI Codex

~/.codex/config.toml or project .codex/config.toml:

codex mcp add homemind-mcp -- npx -y @homemind/mcp

Then set cwd under [mcp_servers.homemind-mcp] to your app root. Manual snippet:

[mcp_servers.homemind-mcp]
command = "npx"
args = ["-y", "@homemind/mcp"]
cwd = "/absolute/path/to/your-arkts-project"

Monorepo / offline entry

After npm run build in packages/mcp:

[mcp_servers.homemind-mcp]
command = "node"
args = ["/absolute/path/to/homemind/packages/mcp/dist/index.js"]
cwd = "/absolute/path/to/your-arkts-project"

Protocol notes

Use stdio; keep stdout for MCP and stderr for logs.