MCP Local Context Memory

我自己的mcp服务器

一家私营、本地经营的公司 模型上下文协议 服务器为Claude提供了一个持久的个人层——自定义工具、文件存储和可搜索的知识库——所有这些都在您的机器上，什么都没有留下。

Claude Code在启动时将服务器作为子进程生成（stdio传输）。没有Docker，没有守护进程，没有开放端口。

使用光标？ MCP服务器可与任何兼容MCP的客户端配合使用。看 CURSOR_SETUP.md 对于特定于Cursor的设置说明，请在Cursor Agent会话中打开它，它将为您配置所有内容。

______________________________________________________________________

它做什么

连接后，Claude可以：

• 存储和检索文件/图像 --按名称保存任何内容，稍后取回
• 维护知识库 --存储笔记、片段和上下文；按意义（语义）或关键字搜索
• 在对话中保持状态 --所有内容都存在于SQLite+本地文件中，并在会话重新启动后幸存下来
• 调用自定义工具 --将Python文件放入 tools/，下次启动时会自动加载
• 可视化知识库 --本地web UI将所有注释显示为交互式图形，按语义相似性进行聚类

______________________________________________________________________

从以前版本升级

如果您已经运行了此服务器并正在拉取新的更改，请在重新启动之前执行以下操作：

1.安装新的依赖项 （没有这些，服务器将无法启动）：

uv sync
# or: pip install --break-system-packages "numpy>=1.24.0" "sentence-transformers>=3.0.0"

2.现有注释的回填嵌入 （语义搜索不返回任何内容）：

# uv:
uv run python3 scripts/backfill_embeddings.py
# pip:
python3 scripts/backfill_embeddings.py

3.注： search_notes 现在默认为语义搜索 这 query 参数现在按含义匹配，而不是按精确的关键字匹配。要保留旧的关键字行为，请传递 keyword=True:

search_notes(query="authentication", keyword=True)

______________________________________________________________________

快速开始

更愿意让你的AI来做吗？ 在Claude Code中打开此仓库，并从粘贴提示 AGENT_SETUP.md --它将为您完成整个设置。否则，请手动执行以下步骤。

1. 安装Python 3.11+

1. 安装MCP SDK。选择一种方法并坚持下去——选择会影响你的 PYTHONPATH 在步骤3中：

选项A-uv（推荐，使用 pyproject.toml):

   uv sync

您的网站包路径将位于内部 .venv/:

   .venv/lib/python3.x/site-packages   # replace 3.x with your Python version

或者用以下方式精确地得到它：

   uv run python3 -c "import site; print(site.getsitepackages()[0])"

选项B-pip（全局安装）：

   pip install "mcp[cli]>=1.0.0"

通过以下方式获取您的网站包路径：

   python3 -c "import site; print(site.getsitepackages()[0])"

1. 复制 .mcp.json.example 到 .mcp.json 并填写你的路径：

   cp .mcp.json.example .mcp.json

编辑 .mcp.json --替换 ` 该目录的绝对路径，以及 ` 使用步骤2中的站点包路径。

1. 重新启动Claude Code——服务器工具将自动出现。

1. *（可选）* 启用 /learn-store-context 和 /learn-load-context 全球技能：

   mkdir -p ~/.claude/skills
   cp -r .claude/skills/learn-store-context ~/.claude/skills/
   cp -r .claude/skills/learn-load-context ~/.claude/skills/

这些技能使Claude能够在对话中总结和恢复会话上下文。如果没有这一步，这些技能仍然可以在这个项目目录中使用，但在其他项目中不可用。

要使服务器在所有项目中全局可用，请在用户范围内注册它：

claude mcp add --scope user my-own-mcp-server \
  --cwd /absolute/path/to/repo \
  -e TRANSPORT=stdio \
  -e PYTHONPATH=$(python3 -c "import site; print(site.getsitepackages()[0])") \
  python3 /absolute/path/to/repo/server.py

这写进 ~/.claude.jsonClaude Code在全球范围内阅读。注： ~/.claude/mcp.json 是 不 由克劳德·科德阅读。

______________________________________________________________________

用法

命令

此存储库附带了两项跨会话内存技能。直接在任何Claude Code对话中键入：

这些可以在这个项目目录中开箱即用。要在任何项目中使用它们，请将它们复制到 ~/.claude/skills/ （请参阅快速入门步骤5）。

______________________________________________________________________

与克劳德（正常模式）

克劳德代码读取 .mcp.json （或全球 ~/.claude.json)并在会话开始时自动生成服务器。你不需要手动运行任何东西——只需与克劳德交谈：

“存储一个注释，其中包含关键的‘项目/决策’、正文‘选择Postgres而不是MySQL来支持JSONB’、标签\[‘项目’、‘决策’\]。”

“在我的笔记中搜索有关身份验证的任何信息。”

“记下‘项目/决策’。”

“列出标记为‘屏幕截图’的所有文件。”

“在我自己的mcp服务器上将此JSON另存为'configs/app.JSON'。” *（Claude自动处理base64编码。）*

服务器进程随着您的Claude Code会话而生灭。您的数据在 data/ 在会话之间持续存在。

手动（检查和调试）

服务器二进制文件可以直接运行进行测试——它讲MCP stdio协议，因此它将阻止等待输入。使用 Ctrl+C 退出：

python3 server.py
# stderr: [tools] Loaded: example_tool.py
# (blocks on stdin — Ctrl+C to exit)

要直接检查存储的数据而不通过Claude：

# List all notes
sqlite3 data/db.sqlite "SELECT key, tags, updated_at FROM notes ORDER BY updated_at DESC;"

# Read a specific note
sqlite3 data/db.sqlite "SELECT body FROM notes WHERE key = 'project/decisions';"

# List all files with sizes
sqlite3 data/db.sqlite "SELECT name, mime_type, size_bytes FROM files;"

# Browse raw files on disk
ls -lh data/files/

______________________________________________________________________

可用工具

这些是服务器公开的底层MCP工具。在正常使用中，你不会直接调用它们——技能(/learn-store-context, /learn-load-context)克劳德自己在后台自动调用它们。如果你想调试或做一些一次性的事情（例如“列出我标记为'project-x'的所有笔记”），你可以显式地调用它们。

系统

文件存储

知识库

______________________________________________________________________

添加您自己的工具

放下一个 .py 归档 tools/:

# tools/my_tool.py

def register(mcp):
    @mcp.tool()
    def greet(name: str) -> str:
        """Greet someone by name."""
        return f"Hello, {name}!"

重新启动克劳德代码。该工具现在可用。看 CLAUDE.md 了解更多工具模式。

______________________________________________________________________

用标签组织

笔记和文件都支持 tags 列表。建议的惯例：

______________________________________________________________________

项目结构

my-own-mcp-server/
├── server.py              # Entry point — init, tool registration, run
├── config.py              # Configuration (DATA_DIR)
├── db.py                  # SQLite setup
├── modules/
│   ├── storage.py         # File storage tools
│   ├── knowledge.py       # Knowledge base tools (semantic search)
│   └── embeddings.py      # sentence-transformers encoder + SQLite blob helpers
├── scripts/
│   └── backfill_embeddings.py  # One-time migration for existing notes
├── tools/                 # Drop custom tools here (auto-loaded)
├── ui/                    # Knowledge base web UI
│   ├── Dockerfile
│   ├── main.py            # FastAPI: /api/graph + /api/notes/:key
│   ├── requirements.txt
│   └── static/            # index.html, app.js, style.css (D3 force graph)
├── docker-compose.yml     # UI service only (MCP server is not in Docker)
├── .claude/
│   └── skills/
│       ├── learn-store-context/   # Skill: summarize and store session context
│       ├── learn-load-context/    # Skill: restore context from a previous session
│       └── learn-start-ui/        # Skill: start the knowledge base UI
├── .mcp.json.example      # Copy to .mcp.json and fill in your paths
├── AGENT_SETUP.md         # Prompt for AI-assisted setup
├── data/                  # Runtime data (gitignored)
│   ├── db.sqlite
│   └── files/
└── pyproject.toml

______________________________________________________________________

存储详细信息

______________________________________________________________________

故意限制

• 无身份验证--仅限本地，单一所有者
• 静态无加密--纯SQLite+文件
• 无自动备份--管理 data/ 你自己
• 无注释/文件版本控制——覆盖具有破坏性
• 无网络暴露——仅通过stdin/stdout与Claude Code通信

______________________________________________________________________

备份

cp data/db.sqlite data/db.sqlite.bak
cp -r data/files data/files.bak

要移动到另一台机器：复制整个 data/ 目录。

______________________________________________________________________

验证

设置后，确认一切正常：

# 1. Verify the server starts
python3 server.py
# Expected stderr: "[tools] Loaded: example_tool.py" then blocks on stdin. Ctrl+C to exit.

# 2. Verify db and files dirs were created
ls data/
# Expected: db.sqlite  files/

sqlite3 data/db.sqlite ".tables"
# Expected: files  notes

然后在克劳德的谈话中：

• ping → 应返回 pong
• store_note 使用测试密钥→ 取回它→ 确认重新启动Claude Code后它仍然存在

______________________________________________________________________

需求

• Python 3.11+
• mcp[cli]>=1.0.0
• numpy>=1.24.0
• sentence-transformers>=3.0.0
• Docker（可选——UI也可以在本地运行 uvicorn)

______________________________________________________________________

数据和隐私

所有数据都保留在您的机器上：

• 文件存储在 data/files/
• 注释和元数据 data/db.sqlite
• 无网络呼叫、无遥测、无外部服务
• 没有开放端口——服务器仅通过stdin/stdout与Claude Code通信

______________________________________________________________________

未来 所有

• SQLite FTS5 --用适当的标记化全文搜索替换基于LIKE的关键字回退
• 注释版本控制 --在覆盖之前保留编辑历史记录
• 出口/进口 — export_all / import_all 用于备份和迁移
• UI：缓存图形布局 --持久化计算位置，这样大型图形就不会在每次加载时重新计算
• UI：搜索栏 --按查询筛选可见节点