Skip to main content
Glama
Sign In
persona-profile-mcp

persona-profile-mcp

by ibeeger
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

persona-profile-mcp

一个本地 MCP server，让 AI 助手在对话中维护人物画像（联系人库）：创建、检索、补充、修正你提到过的人的信息。

面向 MCP 2026-07-28 规范实现：无协议级 session，跨调用状态通过显式 profileId 传递；服务端经 serveStdio 提供，同时兼容 2025 纪元的旧客户端。

详细的使用手册（工具参数、搜索打分规则、典型流程、FAQ）见 docs/USAGE.md。

安装

npm install
npm run build

Related MCP server: Rapport MCP Server

配置

存储位置由 MCP_PROFILE_DIR 决定，默认 ~/.mcp-persona/profiles。每个人一个 JSON 文件，可直接手改、可用 git 版本化。

日志级别由 MCP_PERSONA_LOG 决定：info（默认，含启动提示）/ error（只输出错误）/ silent（完全静默）。日志一律走 stderr。

Claude Code

claude mcp add persona -- node /绝对路径/dist/index.js

Claude Desktop

在 claude_desktop_config.json 里加：

{
  "mcpServers": {
    "persona": {
      "command": "node",
      "args": ["/绝对路径/dist/index.js"],
      "env": { "MCP_PROFILE_DIR": "/绝对路径/profiles" }
    }
  }
}

工具

工具

用途

search_profiles

按姓名/别名/摘要/事实内容模糊搜索

get_profile

按 id 读完整画像（含各条事实的 factId）

list_profiles

按最近更新倒序列出

create_profile

新建画像，重名时返回 duplicateCandidates 提示合并

update_profile

改核心字段，别名增量合并

add_facts

批量追加事实，自动跳过重复

update_fact

修正单条事实（信息过时时用这个，别追加矛盾条目）

delete_fact

删除单条事实

本版不提供 delete_profile。误建的重复画像请手动删除对应的 JSON 文件。

数据结构

{
  "id": "p_7f3a2c91",
  "name": "张伟",
  "aliases": ["Wei", "老张"],
  "relationship": "前同事",
  "summary": "字节推荐算法工程师",
  "facts": [
    {
      "id": "f_3d1e5a02",
      "category": "work",
      "content": "在字节跳动做推荐算法",
      "confidence": "high",
      "source": "2026-08-02 对话",
      "createdAt": "2026-08-02T08:00:00.000Z",
      "updatedAt": "2026-08-02T08:00:00.000Z"
    }
  ],
  "createdAt": "2026-08-02T08:00:00.000Z",
  "updatedAt": "2026-08-02T08:00:00.000Z"
}

category 取值：basic / work / preference / relationship / event / contact / other。 confidence 取值：high / medium / low（默认 medium）。

开发

npm run typecheck
npm test

设计

见 docs/superpowers/specs/2026-08-02-persona-profile-mcp-server-design.md。

Available Tools

8 tools
add_facts追加事实条目A

往已有画像追加一条或多条事实。内容与已有事实重复的会被自动跳过并在 skipped 中报告。若某条信息是对旧信息的更正（如换了工作），请改用 update_fact，避免留下互相矛盾的条目。

Inputs: facts (required), profileId (required). Returns: added, profile, skipped

create_profile创建人物画像A

为一个新的人创建画像。调用前请先用 search_profiles 确认此人没有画像。若返回的 duplicateCandidates 非空，说明可能重复，应改用 update_profile / add_facts 合并。

Inputs: name (required), facts, aliases, summary, +1 more. Returns: profile, duplicateCandidates

delete_fact删除事实条目A
Destructive

从画像中删除一条事实。仅在该信息确认错误或不再相关时使用；若只是过时，优先用 update_fact 改写以保留历史脉络。不要用它逐条清空整份画像来变相删除画像 —— 本 server 没有删除画像的工具，清空只会留下一个没有事实的空壳，仍然出现在搜索与重名检测里；需要删除整份画像时请让用户手动删除对应的 .json 文件。

Inputs: factId (required), profileId (required). Returns: profile, deletedFactId

get_profile读取人物画像A
Read-only

按 id 读取完整人物画像，含全部事实条目及其 factId。id 通常来自 search_profiles 或 list_profiles。

Inputs: profileId (required). Returns: profile

list_profiles列出人物画像A
Read-only

按最近更新时间倒序列出全部人物画像的摘要。用于浏览；按关键词检索请用 search_profiles。

Inputs: limit, offset. Returns: total, profiles

search_profiles搜索人物画像A
Read-only

按姓名、别名、摘要或已记录的事实内容模糊搜索人物画像，返回轻量列表。在记录或查询某人信息前先调用本工具确认此人是否已有画像，避免重复创建。

Inputs: query (required), limit. Returns: results

update_fact修正事实条目A
Idempotent

修改画像中某一条已有事实。信息过时时（换工作、搬城市）应改写原条目，而不是用 add_facts 追加一条互相矛盾的新事实。factId 来自 get_profile。

Inputs: factId (required), profileId (required), source, content, +2 more. Returns: fact, profile

update_profile更新画像核心字段A
Idempotent

修改画像的姓名、关系、摘要，或补充别名。只有显式传入的字段会被修改。aliases 是增量合并（不会删除已有别名）。增删事实请用 add_facts / update_fact / delete_fact。

Inputs: profileId (required), name, aliases, summary, +1 more. Returns: profile

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.2/5.0

    Scored across 8 tools

    Disambiguation4/5

    The tools are mostly distinct: search vs get vs list cover retrieval, create/update cover profile lifecycle, and add/update/delete cover facts. The main potential confusion is between add_facts (append new) and update_fact (modify existing), but the descriptions provide clear guidelines on when to use each. update_profile and update_fact are also distinct (profile-level vs fact-level).

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern: search_profiles, get_profile, list_profiles, create_profile, update_profile, add_facts, update_fact, delete_fact. Retrieval verbs (search/get/list) and mutation verbs (create/update/add/delete) are cleanly separated with consistent snake_case.

    Tool Count5/5

    8 tools is a well-scoped set for a persona profile server. Each tool has a clear purpose covering retrieval, profile management, and fact management. The count is neither thin nor bloated for the domain.

    Completeness4/5

    The server covers the full lifecycle well: search/get/list, create/update for profiles, and add/update/delete for facts. The intentional absence of a delete_profile tool is documented as a design decision (with workaround guidance), and there's no glaring missing operation for the core workflow.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Rapport MCP Server

      sssst1118
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to query local conversation transcripts and relationship data via a local MCP server, allowing retrieval of past conversations and facts about people.
      1
      AGPL 3.0

    • carddav-mcp

      dominik1001
      A
      license
      Not graded
      quality
      D
      maintenance
      A CardDAV MCP server that exposes contacts and address books as tools for AI assistants.
      8 npm
      1
      MIT

    • tilde

      topskychen
      A
      license
      Not graded
      quality
      D
      maintenance
      A privacy-first MCP server that acts as the universal memory and profile layer for AI agents, enabling profile management, skills, resume import, and team sync.
      4
      MIT