deerdawn

DeerDawn MCP Server

永不从零开始。每个新的 AI 会话一开始就已了解你的项目。

DeerDawn 是 AI 会话记忆——你 AI 的参谋长——适用于 Claude Code、Claude.ai、Claude Desktop、ChatGPT、Cursor、Windsurf、VS Code、Zed、Codex 以及其他任何兼容 MCP 的 Agent。无论在哪里启动会话，start_session 都会向 Agent 提供简报：你正在做什么、已经做出哪些决定，以及目前有什么阻碍——让每个会话都不必从零开始。

关于此代码库。 DeerDawn 是一项托管服务。此代码库包含公开安装指南、 发布到 MCP 注册表的 server.json 清单，以及用于启动已发布 npm 包的 Dockerfile。 服务本身通过 npm 以 @deerdawn/mcp-server 发布； 其源代码不开源。欢迎在此提交问题和提问。

快速开始——托管服务（推荐，无需安装）

连接到托管 MCP 端点。无需 API 密钥——首次调用 DeerDawn 工具时，通过浏览器登录即可。

Claude Code

claude mcp add -s user --transport http deerdawn https://api.deerdawn.com/api/v1/mcp

其他所有工具——使用此 URL 添加远程 MCP 服务（有时称为连接器）：

https://api.deerdawn.com/api/v1/mcp

工具	位置
Claude.ai	设置 → 连接器 → 添加自定义连接器
ChatGPT.com	设置 → 连接器 → 添加 MCP 服务（选择 OAuth）
Cursor	设置 → MCP → 添加服务，或在 .cursor/mcp.json 中添加 "url" 条目
VS Code / Copilot	命令面板 → MCP: 添加服务 → HTTP → 粘贴 URL
Windsurf、Gemini 等	使用此 URL 添加自定义远程 / HTTP MCP 服务

OAuth 客户端字段留空。点击 Connect（或重启工具），并在 DeerDawn 标签页打开后登录。如果工具连接时没有提示登录，首次调用 DeerDawn 工具会返回登录 URL——打开该 URL，登录一次，然后重试调用；设置会自动完成。

然后说：“启动一个 DeerDawn 会话。”

托管服务提供 18 个核心会话记忆工具。如需写入代码库文件、使用自动捕获钩子以及完整的 35 个工具集，请使用下方的本地安装方式。

---

本地安装（stdio）——可选升级

如果你想要更深入的集成，可以通过 npx -y @deerdawn/mcp-server@latest 在你的计算机上运行服务：

• 将 .deerdawn-context.md / .cursorrules 写入代码库，无需调用工具即可加载上下文。
• 安装 SessionStart / Stop 钩子，自动捕获并刷新上下文。
• 提供完整的 35 个工具集（托管服务提供 18 个核心工具）。

登录方式相同——默认使用浏览器 OAuth，无需 API 密钥。首次运行且没有凭据时，服务会启动设备授权流程：URL 会打印到 stderr，保存到 ~/.deerdawn/pending-auth.json，并通过 get_auth_status 工具直接返回（在看不到 stderr 的 GUI 宿主中使用该工具）。你在浏览器中批准后，凭据会保存到 ~/.deerdawn/credentials.json，之后的每个会话都会通过身份验证。

更倾向于使用非交互式身份验证（CI、无头模式、SSH）？在 app.deerdawn.com → 设置 → API 密钥中创建密钥（以 dd_ 开头），并在配置的 env 块中设置 DEERDAWN_API_KEY——这样会完全跳过浏览器登录。

Claude Code（命令行）

运行设置命令——它会一步完成服务注册、登录和钩子配置：

npx -y @deerdawn/mcp-server@latest setup

也可以手动注册（使用用户级范围，使其适用于所有项目）：

claude mcp add -s user deerdawn -e DEERDAWN_API_URL=https://api.deerdawn.com -e DEERDAWN_SURFACE_ID=claude_code -- npx -y @deerdawn/mcp-server@latest

注册后重启 Claude Code。如果你尚未登录，请调用 get_auth_status——它会返回用于完成登录的浏览器 URL。

---

Claude Desktop

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "deerdawn": {
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server@latest"],
      "env": {
        "DEERDAWN_API_URL": "https://api.deerdawn.com"
      }
    }
  }
}

---

Cursor

~/.cursor/mcp.json（macOS、Linux 和 Windows 上的路径相同）：

{
  "mcpServers": {
    "deerdawn": {
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server@latest"],
      "env": {
        "DEERDAWN_API_URL": "https://api.deerdawn.com"
      }
    }
  }
}

---

Windsurf

macOS：~/.codeium/windsurf/mcp_config.json Windows：%APPDATA%\Codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "deerdawn": {
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server@latest"],
      "env": {
        "DEERDAWN_API_URL": "https://api.deerdawn.com"
      }
    }
  }
}

---

VS Code（GitHub Copilot / Continue）

添加到 .vscode/settings.json 或用户的 settings.json：

{
  "mcp": {
    "servers": {
      "deerdawn": {
        "command": "npx",
        "args": ["-y", "@deerdawn/mcp-server@latest"],
        "env": {
          "DEERDAWN_API_URL": "https://api.deerdawn.com"
        }
      }
    }
  }
}

对于 Continue（~/.continue/config.json）：

{
  "mcpServers": [
    {
      "name": "deerdawn",
      "command": "npx",
      "args": ["-y", "@deerdawn/mcp-server@latest"],
      "env": {
        "DEERDAWN_API_URL": "https://api.deerdawn.com"
      }
    }
  ]
}

---

Zed

添加到 ~/.config/zed/settings.json：

{
  "context_servers": {
    "deerdawn": {
      "command": {
        "path": "npx",
        "args": ["-y", "@deerdawn/mcp-server@latest"],
        "env": {
          "DEERDAWN_API_URL": "https://api.deerdawn.com"
        }
      }
    }
  }
}

---

Codex（OpenAI）

添加到 ~/.codex/config.toml：

[mcp_servers.deerdawn]
command = "npx"
args = ["-y", "@deerdawn/mcp-server@latest"]
startup_timeout_sec = 120

[mcp_servers.deerdawn.env]
DEERDAWN_API_URL = "https://api.deerdawn.com"

---

要在以上任一配置中跳过浏览器登录，请在 env 块中添加 "DEERDAWN_API_KEY": "dd_your_key_here"（Codex TOML：在 [mcp_servers.deerdawn.env] 下添加 DEERDAWN_API_KEY = "dd_your_key_here"）。

---

主机命名说明

有些 MCP 主机会为工具名添加服务前缀（例如 deerdawn-get_auth_status），而不是使用不带前缀的名称（get_auth_status）。 如果找不到某个工具，请尝试使用带 deerdawn- 前缀的名称。

---

环境变量

所有环境变量均为可选项。即使不设置任何环境变量，服务也会启动并引导你完成浏览器登录。

变量	必需	默认值	描述
DEERDAWN_API_URL	否	https://api.deerdawn.com	API 基础 URL。仅在可自托管或使用预发布环境时更改。
DEERDAWN_SURFACE_ID	否	自动检测	此服务运行所在的工具（claude_code、cursor、codex）。未设置时会从 MCP 客户端检测；显式设置可固定会话归属。
DEERDAWN_API_KEY	否	—	用于非交互式身份验证（CI/无头环境）的 API 密钥（dd_...）。默认使用浏览器 OAuth 登录。可在 app.deerdawn.com → Settings → API Keys 获取。

---

会话记忆工具

本地服务提供 35 个工具（托管远程服务提供 18 个核心工具）。以下工具适用于每个会话。

start_session

在每个会话开始时调用此工具。 返回当前目录对应项目的活动上下文，以及所有其他项目的简要概览——仅需一次 API 调用，总计约 100–180 个 token。不要分别调用 list_context_map 和 get_context；此工具可替代两者。

update_context

推送上下文更新。在以下情况发生时调用此工具：做出决定、当前任务变更、发现阻碍，或取得重要进展。不要等到会话结束才更新——更新成本很低，也能确保每个新会话读取到最新的简报。

project_id: "proj-abc123"
summary: "Switched auth from JWT to session tokens — JWT had XSS risk via localStorage. Now using Redis-backed sessions."

get_context

按分区获取项目上下文。默认返回 [task, status]（约 30 个 token）。传入 sections=["all"] 可获取全部内容。

project_id: "proj-abc123"
sections: ["task", "decisions", "blocking"]

import_local_context

从当前目录下的 CLAUDE.md、AGENTS.md 或 .cursorrules 导入上下文。先不要传入 confirmed: true——这会显示待导入内容的免费预览。然后再次调用并传入 confirmed: true 以确认导入。

complete_setup

适用于不稳定主机的一站式设置备用方案：检查身份验证状态，为某个工具界面应用本地设置，并在找到本地文件时运行 import_local_context 预览和确认流程。

示例：

complete_setup
{
  "surface": "cursor"
}

cleanup_context

在交接或完成任务时清理任务状态。使用此工具将活动任务标记为已完成，并清除未完成任务的命令历史记录，让下一个 Agent 看到干净的状态。

当任务明确完成且没有未解决的问题时，请自动调用此工具并设置 complete_task=true（无需额外确认）。

cleanup_context
{
  "complete_task": true
}

search_context

搜索所有项目。例如："关于身份验证的决策"、"使用 PostgreSQL 的项目"、"账单工作有哪些阻碍"。

list_projects

列出所有项目的 ID 和最后更新时间戳。只有在明确需要项目索引时才使用此工具。正常启动时，优先使用 start_session。

create_project

开始处理没有现有项目条目的事项时，创建一个新项目。

---

工作区知识工具

get_workspace_overview

在会话开始时使用 mode=startup 获取简洁的方向指引简报。当用户询问“我在做什么？”或想了解更全面的情况时，使用 mode=overview。

get_workspace_entities

深入了解类型化的工作区知识：决策、工具、环境和能力。可按 types、query、status 或 project_id 筛选。

get_project_map

返回持久化的文件级项目记忆：常用路径、入口点、命名界面和调试说明。当路径可能已知时，在全仓库搜索前使用此工具。

find_known_paths

在 DeerDawn 的持久化路径记忆中搜索，例如 "auth modal" 或 "signup route"，然后再使用仓库搜索。

get_next_best_context

根据当前工具和工作目录，获取接下来要提取哪些上下文的排序建议。

upsert_workspace_entities

创建或更新持久化的工作区知识——适用于多个项目的工具、环境、架构决策或能力。

record_hot_paths

将发现的文件或文件夹路径写回 DeerDawn，以便后续会话无需重新发现即可快速了解项目。

record_debug_finding

存储简洁、持久化的调试结果，可选择关联特定路径。

---

工作原理

全新的 AI 会话对你的项目一无所知——只能从零开始。DeerDawn 会直接提供项目简报。

You work in Claude Code, Cursor, or ChatGPT
  → DeerDawn captures the session (via MCP, browser extension, or desktop app)
  → Extraction pipeline distills what changed (task, decisions, blockers, stack) into the brief
  → The brief is stored per-project in your workspace and kept current
  → Next session would start cold — instead start_session hands it the brief in one call
  → Every new session opens already briefed, never from a blank slate

简报按项目存储。关键决策会标记出来，并始终优先显示，不受令牌预算影响。如果部分内容被删减，你会确切看到哪些内容被删掉，以及如何取回。

---

验证安装

保存配置并重启 Agent 后，先调用 start_session：

start_session

如果它返回当前项目的上下文，说明 DeerDawn 已连接，无需再做其他操作。（如果你通过托管的远程服务 / claude.ai 连接器而非本地服务进行连接，这是正常情况：该版本中不会提供 apply_setup 和 import_local_context，也不需要它们——上下文会自动加载。）

如果 start_session 提示你尚未通过身份验证，请完成登录并导入初始上下文：

get_auth_status
import_local_context
import_local_context {"confirmed":true}
start_session
cleanup_context {"complete_task":true}

如果你的宿主会给工具名称添加前缀，请改用 deerdawn-get_auth_status 和 deerdawn-import_local_context。

如果你的宿主在设置期间运行不稳定，可运行 complete_setup {"surface":"claude_code"}，作为一次调用的备用方案——它会检查身份验证、自动应用界面设置，并在一次调用中导入本地上下文。apply_setup 会在内部调用，无需手动运行。

你应该会收到当前项目的上下文（如果这是一个新的工作区，则会收到导入本地上下文的提示）。如果收到错误而非上下文：

• 调用 get_auth_status，并通过返回的 URL 完成浏览器登录（如果设置了 DEERDAWN_API_KEY，请确认其以 dd_ 开头）
• 完全重启 Agent（不要只重新加载）
• 检查 MCP 日志：~/Library/Logs/Claude/mcp*.log（Claude Desktop）或相应位置

---

故障排查

DeerDawn 工具没有显示在你的 Agent 中 服务启动时不需要任何环境变量——缺少 API 密钥不会阻止启动。如果没有 DeerDawn 工具显示：

1. 保存配置后，完全重启编辑器（不要只重新加载）
2. 检查 MCP 日志：
   • Claude Desktop：~/Library/Logs/Claude/mcp*.log
   • Cursor：视图 → 输出 → MCP
   • Windsurf：帮助 → 切换开发者工具 → 控制台
   • VS Code：输出面板 → MCP
   • Zed：帮助 → 切换开发工具 → 控制台

身份验证错误／尚未登录 调用 get_auth_status——它会返回浏览器登录 URL。打开该 URL 并批准，然后重试工具调用；设置会自动完成。如果设置了 DEERDAWN_API_KEY，其值必须以 dd_ 开头。

登录提示触发速率限制（HTTP 429） 在设置过程中快速重启多次后会出现此情况。重试前请等待一分钟——立即重新运行设置仍会触发速率限制。

start_session 未返回项目 调用 import_local_context（先不要设置 confirmed: true），从当前目录中的 CLAUDE.md 或 AGENTS.md 导入上下文。

响应缓慢 提取流水线会在首次导入时运行。后续调用 start_session 会很快（使用缓存的上下文查找；除非内容发生变化，否则不会调用大模型）。

---

开发

npm install
npm run build   # compile TypeScript
npm run dev     # watch mode
npm test        # run tests
npm run lint

---

许可证

MIT