atlas-introspect-mcp

一个 MCP 服务器，让 ATLAS 能够查看——并编辑——它自身：

为什么通过 HTTP API

聊天历史、工作区和提示词都存储在一个 DuckDB 文件（data/chat_history.db）中。DuckDB 是单写入者，而 ATLAS 进程在其整个生命周期内持有该写锁——第二个进程打开该文件，即使是只读，也会因锁冲突而失败。因此，此服务器通过环回 HTTP 向 ATLAS 发起请求。这也意味着按用户划分的作用域由 ATLAS 强制执行，而不是在此处重新实现。

只有 mcp.json 和 prompts/*.md 被直接修改；ATLAS 对这两者都没有 API。

作为一个独立进程，正是回调 ATLAS 的安全性所在：ATLAS 等待此服务器的 stdio 回复，同时其自身的事件循环保持空闲以处理请求。进程内工具做同样的事情会导致死锁。

Related MCP server: Atlas MCP Server

身份标识

每个查询都限定在一个用户范围内，以 X-User-Email 发送。当 DEBUG_MODE=true 时，ATLAS 会尊重该标头；当它关闭时，该标头就是认证代理本应提供的值，因此同一个标志在两种情况下都有效。默认值是 test@test.com——这是 ATLAS 在调试模式下回退到的测试用户，因此也是通过此主机上的 UI 创建的对话的所有者。

安装

git clone https://github.com/garland3/atlas-introspect-mcp
cd atlas-introspect-mcp
uv venv .venv
uv pip install -e ".[dev]" --python .venv/bin/python

独立检查（在 ATLAS 运行时）：

.venv/bin/atlas-introspect-mcp --list-tools
.venv/bin/python -c "
import asyncio; from fastmcp import Client
from fastmcp.client.transports import StdioTransport
async def m():
    async with Client(StdioTransport(command='.venv/bin/atlas-introspect-mcp', args=['--stdio'])) as c:
        print(await c.call_tool('atlas_status', {}))
asyncio.run(m())"

注册到 ATLAS

添加到你的 ATLAS config/mcp.json 中（使用绝对路径——命令是在服务管理器的 PATH 中查找的，而不是你的 shell 的），然后重启 ATLAS：

"atlas_introspect": {
  "command": [
    "/abs/path/to/atlas-introspect-mcp/.venv/bin/atlas-introspect-mcp",
    "--stdio",
    "--atlas-url", "http://127.0.0.1:8090",
    "--user", "test@test.com"
  ],
  "cwd": "/abs/path/to/atlas-introspect-mcp",
  "transport": "stdio",
  "groups": ["users"],
  "description": "Introspect and configure this ATLAS instance: browse chat history, read/edit config/mcp.json, manage workspaces and custom prompts.",
  "short_description": "ATLAS self-introspection",
  "compliance_level": "Public"
}

在命令中添加 "--read-only" 以构建只读版本；此时每个修改工具都会拒绝执行而不是写入。

端口：stdio 不需要端口。--transport http 默认为 8101。它直接拒绝端口 8080——在运行 k3s 的主机上，klipper-lb 将 8080 DNAT 到 Traefik，包括在 127.0.0.1 上，因此绑定在那里的服务器收不到任何请求，每个请求都会以空的 500 返回，且日志中没有一行记录。

配置

每个标志都有对应的环境变量。

工具

对话（只读） — list_conversations、search_conversations、get_conversation、list_conversation_tags

config/mcp.json — get_mcp_config、upsert_mcp_server、delete_mcp_server、replace_mcp_config

工作区 — list_workspaces、create_workspace、update_workspace、delete_workspace

自定义提示词 — list_custom_prompts、get_custom_prompt、create_custom_prompt、update_custom_prompt、delete_custom_prompt

磁盘上的提示词文件 — list_prompt_files、read_prompt_file、write_prompt_file

健康检查 — atlas_status

需要注意的坑

• mcp.json 的编辑不会立即生效。 ATLAS 在启动时生成 stdio 服务器。每个写入工具都会在其结果中说明这一点；使用 systemctl --user restart atlas 或 ./redeploy.sh --no-pull 来应用。

• 编辑自己的条目是可行的，但只在重启后生效——到那时，如果条目损坏，此服务器就消失了，你无法从 ATLAS 内部修复它。备份会以 mcp.json.bak-<stamp> 的形式放在文件旁边。

• upsert_mcp_server 是整体替换条目，不会合并。先读取它，修改它，然后把整个内容发回去。工作区的 config 和提示词的 content 也是如此。

• 对话工具在设计上就是只读的。 ATLAS 中有删除端点；这里故意不暴露它们。

• write_prompt_file 会改变实例中的每个聊天。 它会先备份，并且像 mcp.json 一样，在下次重启时生效。

测试

.venv/bin/pytest

它们针对临时目录覆盖了文件编辑和验证逻辑（原子写入、备份、路径遍历拒绝、lint 警告、只读模式）——不需要运行中的 ATLAS。