@aiperson/mcp-server

Model Context Protocol server for the dotPerson Memory Layer. Plugs into Claude Code, VS Code, Cursor, Antigravity, GitHub Copilot — anywhere that speaks MCP — and exposes the user's .person persona as a set of tools the model can read and append to.

Ships two binaries:

| Binary | What it is | |---|---| | dotperson-mcp | The stdio MCP server. Wired into your AI tool's mcp.json / settings.json so the model can call persona tools. | | personkit-stop-hook | Claude Code Stop-hook companion. Reads the Stop payload from stdin, counts user messages in the transcript, and emits a block decision every Nth (default N=10) so Claude pauses to consider whether the conversation warrants a persona update. |

Install (recommended — one command)

# Install the personkit CLI (Rust):
brew install dotperson/tap/personkit   # coming with brew formula
# or: cargo install --git https://github.com/humphreytheodore/dotPerson personkit-cli

# Auth:
personkit login

# Wire this server into every detected AI tool on the machine:
personkit connect --all

personkit connect safely merges the right config into Claude Code, VS Code, Cursor, GitHub Copilot, and Google Antigravity — preserving every user-owned field byte-identical. Re-running is a no-op when the persona hasn't changed.

Install (manual)

If you'd rather wire it yourself, the underlying invocations are:

Claude Code — ~/.claude/settings.json:

{
  "mcpServers": {
    "dotperson": {
      "command": "npx",
      "args": ["-y", "-p", "@aiperson/mcp-server@latest", "dotperson-mcp"]
    }
  },
  "hooks": {
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "npx -y -p @aiperson/mcp-server@latest personkit-stop-hook"
          }
        ]
      }
    ]
  }
}

VS Code (native MCP) — ~/Library/Application Support/Code/User/mcp.json (macOS):

{
  "servers": {
    "dotperson": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "@aiperson/mcp-server@latest", "dotperson-mcp"]
    }
  }
}

Cursor — ~/.cursor/mcp.json:

{
  "mcpServers": {
    "dotperson": {
      "command": "npx",
      "args": ["-y", "-p", "@aiperson/mcp-server@latest", "dotperson-mcp"]
    }
  }
}

Authentication

Reads ~/.dotperson/credentials.json for a Firebase ID token + refresh token. Refreshes transparently via the Firebase secure-token endpoint when the cached ID token is within 60 s of expiry.

Get credentials via personkit login — opens a browser, signs in via GitHub through Firebase, captures the token pair, writes them to disk with mode 0600.

Tools (v0)

| Tool | What it does | |---|---| | read_persona | Returns the user's full persona JSON. Use to ground responses in the user's voice / values / conventions. | | get_voice | Returns just the persona.voice block. Cheaper than read_persona when voice is all you need. | | write_value | Append to persona.values_held. Use sparingly — values shape every interaction. | | write_convention | Append to persona.conventions_agreed. Use when the user explicitly agrees a way of working. | | update_voice | Partial-update persona.voice (currently just register). |

Per the Lean Posture decision §3 cut #8, the v0 surface is 5 tools instead of the eventual 18. Additional tools (add_refusal, append_relational_history, list_pairings, grant_consent, record_substrate_transition, whoami, etc.) land once Claude actually tries to call them.

What this server is NOT responsible for

• Deciding when to write. That's the Stop hook (personkit-stop-hook bin in this package). The hook nudges the model every N exchanges to consider whether the conversation warrants a persona update; the model then decides whether to call any write tools.
• Persisting persona content. That's the relay
  • the user's git repo. This server is a pass-through with auth and tiny ergonomic wrappers.
• Conflict resolution between surfaces. That's the relay's Automerge merge engine. This server just fires writes; concurrent writes from other surfaces merge deterministically server-side.

Dev (from source)

git clone https://github.com/humphreytheodore/dotPerson
cd dotPerson/engineering/mcp-server
npm install
npm run dev     # tsx — no build step
# or: npm run build && node dist/index.js

The server runs over stdio per the MCP spec, so you can't curl it. The cleanest way to exercise it locally is to wire it into an MCP host (Claude Code) — point the config at your built dist/index.js or use PERSONKIT_MCP_COMMAND=node PERSONKIT_MCP_BIN=node PERSONKIT_MCP_ARGS="$(pwd)/dist/index.js" personkit connect --tool claude-code so personkit connect writes your local-build invocation.

License

Apache-2.0.