我自己的mcp服务器
一家私营、本地经营的公司 模型上下文协议 服务器为Claude提供了一个持久的个人层——自定义工具、文件存储和可搜索的知识库——所有这些都在您的机器上,什么都没有留下。
Claude Code在启动时将服务器作为子进程生成(stdio传输)。没有Docker,没有守护进程,没有开放端口。
> 使用光标? MCP服务器可与任何兼容MCP的客户端配合使用。看 CURSOR_SETUP.md 对于特定于Cursor的设置说明,请在Cursor Agent会话中打开它,它将为您配置所有内容。
它做什么
| 没有此服务器 | 有此服务器 |
|---|---|
| 每次会话都重新解释项目上下文 | 用一次工具调用加载上下文 |
| 生成的代码只存在于聊天历史中 | 生成的工件无限期存在 |
| Claude会忘记您的偏好和决定 | 永久存储,始终可检索 |
| 搜索旧聊天记录 | 立即按关键字搜索笔记 |
| 重复生成相同的样板 | 存储一次,随时检索和调整 |
| 上下文窗口是唯一的内存 | 实际上是无限的持久内存 |
连接后,Claude可以:
- 存储和检索文件/图像 --按名称保存任何内容,稍后取回
- 维护知识库 --存储笔记、片段和上下文;按意义(语义)或关键字搜索
- 在对话中保持状态 --所有内容都存在于SQLite+本地文件中,并在会话重新启动后幸存下来
- 调用自定义工具 --将Python文件放入
tools/,下次启动时会自动加载 - 可视化知识库 --本地web UI将所有注释显示为交互式图形,按语义相似性进行聚类
从以前版本升级
如果您已经运行了此服务器并正在拉取新的更改,请在重新启动之前执行以下操作:
1.安装新的依赖项 (没有这些,服务器将无法启动):```bash
uv sync
or: pip install --break-system-packages "numpy>=1.24.0" "sentence-transformers>=3.0.0"
**2.现有注释的回填嵌入** (语义搜索不返回任何内容):```bash
# 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`):**```bash
uv sync
您的网站包路径将位于内部 .venv/:```bash
.venv/lib/python3.x/site-packages # replace 3.x with your Python version
或者用以下方式精确地得到它:```bash
uv run python3 -c "import site; print(site.getsitepackages()[0])"
选项B-pip(全局安装):```bash
pip install "mcp[cli]>=1.0.0"
通过以下方式获取您的网站包路径:```bash
python3 -c "import site; print(site.getsitepackages()[0])"
- 复制
.mcp.json.example到.mcp.json并填写你的路径:```bash
cp .mcp.json.example .mcp.json
编辑 `.mcp.json` --替换 `` 该目录的绝对路径,以及 `` 使用步骤2中的站点包路径。
1. 重新启动Claude Code——服务器工具将自动出现。
1. *(可选)* 启用 `/learn-store-context` 和 `/learn-load-context` 全球技能:```bash
mkdir -p ~/.claude/skills
cp -r .claude/skills/learn-store-context ~/.claude/skills/
cp -r .claude/skills/learn-load-context ~/.claude/skills/
这些技能使Claude能够在对话中总结和恢复会话上下文。如果没有这一步,这些技能仍然可以在这个项目目录中使用,但在其他项目中不可用。
要使服务器在所有项目中全局可用,请在用户范围内注册它:```bash
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.json`Claude Code在全球范围内阅读。注: `~/.claude/mcp.json` 是 **不** 由克劳德·科德阅读。
______________________________________________________________________
## 用法
### 命令
此存储库附带了两项跨会话内存技能。直接在任何Claude Code对话中键入:
|命令|它的作用|
|---|---|
| `/learn-store-context` |总结当前对话并将其另存为笔记——在会话结束时运行此操作|
| `/learn-load-context` |加载并回读以前存储的摘要——在新会话开始时运行此程序,从您停止的地方继续|
| `/learn-start-ui` |在以下位置启动知识库UIhttp://localhost:8000 |
这些可以在这个项目目录中开箱即用。要在任何项目中使用它们,请将它们复制到 `~/.claude/skills/` (请参阅快速入门步骤5)。
______________________________________________________________________
### 与克劳德(正常模式)
克劳德代码读取 `.mcp.json` (或全球 `~/.claude.json`)并在会话开始时自动生成服务器。你不需要手动运行任何东西——只需与克劳德交谈:
> “存储一个注释,其中包含关键的‘项目/决策’、正文‘选择Postgres而不是MySQL来支持JSONB’、标签\[‘项目’、‘决策’\]。”
> “在我的笔记中搜索有关身份验证的任何信息。”
> “记下‘项目/决策’。”
> “列出标记为‘屏幕截图’的所有文件。”
> “在我自己的mcp服务器上将此JSON另存为'configs/app.JSON'。” *(Claude自动处理base64编码。)*
服务器进程随着您的Claude Code会话而生灭。您的数据在 `data/` 在会话之间持续存在。
### 手动(检查和调试)
服务器二进制文件可以直接运行进行测试——它讲MCP stdio协议,因此它将阻止等待输入。使用 `Ctrl+C` 退出:```bash
python3 server.py
# stderr: [tools] Loaded: example_tool.py
# (blocks on stdin — Ctrl+C to exit)
要直接检查存储的数据而不通过Claude:```bash
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'的所有笔记”),你可以显式地调用它们。
### 系统
|工具|说明|
|---|---|
| `ping` |健康检查--确认服务器可访问|
### 文件存储
|工具|说明|
|---|---|
| `store_file(name, content_base64, mime_type, tags[])` |保存文件、图像或文档|
| `get_file(name)` |按名称检索文件内容|
| `list_files(tag?)` |列出所有存储的文件(可选按标签筛选)|
| `delete_file(name)` |删除存储的文件|
### 知识库
|工具|说明|
|---|---|
| `store_note(key, body, tags[])` |保存文字注释或片段|
| `get_note(key)` |按键检索笔记|
| `search_notes(query, keyword?)` |默认语义搜索;通过 `keyword=True` 用于基于LIKE的精确搜索|
| `list_notes(tag?)` |列出所有注释(可选按标签筛选)|
| `delete_note(key)` |删除注释|
______________________________________________________________________
## 添加您自己的工具
放下一个 `.py` 归档 `tools/`:```python
# 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 列表。建议的惯例:
| 模式 | 示例 |
|---|---|
| 按项目 | project-name |
| 按类型 | snippet, config, screenshot, reference |
| 按语言 | python, sql, bash |
| 按状态 | wip, done, archived |
项目结构```
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
______________________________________________________________________
## 存储详细信息
|方面|细节|
|---|---|
|文件位置| `data/files/` --保留路径结构|
|数据库| `data/db.sqlite` |
|最大文件大小|无强制限制--受磁盘空间限制|
|注释体大小|没有强制限制——SQLite TEXT是无界的|
|标记格式|JSON数组存储为TEXT: `["tag1","tag2"]` |
|反常行为| `store_file` 和 `store_note` 覆盖密钥冲突|
______________________________________________________________________
## 故意限制
- 无身份验证--仅限本地,单一所有者
- 静态无加密--纯SQLite+文件
- 无自动备份--管理 `data/` 你自己
- 无注释/文件版本控制——覆盖具有破坏性
- 无网络暴露——仅通过stdin/stdout与Claude Code通信
______________________________________________________________________
## 备份```bash
cp data/db.sqlite data/db.sqlite.bak
cp -r data/files data/files.bak
要移动到另一台机器:复制整个 data/ 目录。
验证
设置后,确认一切正常:```bash
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→ 应返回pongstore_note使用测试密钥→ 取回它→ 确认重新启动Claude Code后它仍然存在
需求
- Python 3.11+
mcp[cli]>=1.0.0numpy>=1.24.0sentence-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:搜索栏 --按查询筛选可见节点
