# deerdawn [Health: Active] **Category:** 🧠 Knowledge & Memory **Repository:** https://github.com/HissingSpider/deerdawn-mcp **GitHub Stars:** 0 **npm Downloads (last month):** 34 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/deerdawn-2 ## Description AI session memory: the brief your AI reads before every session so no session starts cold. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `npx` (confidence: high): ```json "mcpServers": { "deerdawn": { "command": "npx", "args": ["-y","@deerdawn/mcp-server@latest"] } } ``` ## Documentation & README # DeerDawn MCP Server Never start cold. Every new AI session opens already briefed on your project. DeerDawn is AI session memory β€” your AI's chief of staff β€” for Claude Code, Claude.ai, Claude Desktop, ChatGPT, Cursor, Windsurf, VS Code, Zed, Codex, and any other MCP-compatible agent. Start a session anywhere and `start_session` hands the agent the brief: what you were working on, what was decided, and what's blocking β€” so no session starts cold. > **About this repository.** DeerDawn is a hosted service. This repo holds the > public install guide, the `server.json` manifest published to the MCP registry, > and a Dockerfile that launches the published npm package. The server itself > ships from npm as [`@deerdawn/mcp-server`](https://www.npmjs.com/package/@deerdawn/mcp-server); > its source is not open. Issues and questions are welcome here. ## Quick start β€” hosted server (recommended, no install) Connect to the hosted MCP endpoint. **No API key needed** β€” you sign in with your browser the first time a DeerDawn tool is called. **Claude Code** ```bash claude mcp add -s user --transport http deerdawn https://api.deerdawn.com/api/v1/mcp ``` **Every other tool** β€” add a remote MCP server (sometimes called a connector) with this URL: ``` https://api.deerdawn.com/api/v1/mcp ``` | Tool | Where | |------|-------| | Claude.ai | Settings β†’ Connectors β†’ Add custom connector | | ChatGPT.com | Settings β†’ Connectors β†’ Add MCP server (choose OAuth) | | Cursor | Settings β†’ MCP β†’ Add server, or add a `"url"` entry in `.cursor/mcp.json` | | VS Code / Copilot | Command palette β†’ MCP: Add Server β†’ HTTP β†’ paste the URL | | Windsurf, Gemini, others | Add a custom remote / HTTP MCP server with the URL | Leave any OAuth client fields blank. Click Connect (or restart the tool) and sign in when the DeerDawn tab opens. If your tool connects without prompting for sign-in, the first DeerDawn tool call returns the sign-in URL β€” open it, sign in once, and retry the call; setup completes automatically. Then say: **"Start a DeerDawn session."** The hosted server exposes 18 core session-memory tools. For repo-file writes, automatic capture hooks, and the full 35-tool set, use the local install below. --- ## Local install (stdio) β€” optional upgrade Run the server on your machine via `npx -y @deerdawn/mcp-server@latest` when you want deeper integration: - Writes `.deerdawn-context.md` / `.cursorrules` into your repo so context loads with no tool call. - Installs SessionStart / Stop hooks that capture and flush context automatically. - Exposes the full set of 35 tools (the hosted server exposes 18 core ones). **Sign-in works the same way** β€” browser OAuth by default, no API key required. On first run without credentials, the server starts a device-flow sign-in: the URL is printed to stderr, saved to `~/.deerdawn/pending-auth.json`, and returned in-band by the `get_auth_status` tool (use that in GUI hosts where stderr isn't visible). After you approve in the browser, credentials are saved to `~/.deerdawn/credentials.json` and every future session is authenticated. **Prefer non-interactive auth** (CI, headless, SSH)? Create a key at [app.deerdawn.com](https://app.deerdawn.com) β†’ Settings β†’ API Keys (it starts with `dd_`) and set `DEERDAWN_API_KEY` in the config's `env` block β€” browser sign-in is then skipped entirely. ### Claude Code (CLI) Run the setup command β€” it registers the server, signs you in, and configures hooks in one step: ```bash npx -y @deerdawn/mcp-server@latest setup ``` Or register manually (user scope so it works across all projects): ```bash 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 ``` Restart Claude Code after registering. If you haven't signed in yet, call `get_auth_status` β€” it returns the browser URL to complete sign-in. --- ### Claude Desktop **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "deerdawn": { "command": "npx", "args": ["-y", "@deerdawn/mcp-server@latest"], "env": { "DEERDAWN_API_URL": "https://api.deerdawn.com" } } } } ``` --- ### Cursor `~/.cursor/mcp.json` (same path on macOS, Linux, and Windows): ```json { "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` ```json { "mcpServers": { "deerdawn": { "command": "npx", "args": ["-y", "@deerdawn/mcp-server@latest"], "env": { "DEERDAWN_API_URL": "https://api.deerdawn.com" } } } } ``` --- ### VS Code (GitHub Copilot / Continue) Add to `.vscode/settings.json` or user `settings.json`: ```json { "mcp": { "servers": { "deerdawn": { "command": "npx", "args": ["-y", "@deerdawn/mcp-server@latest"], "env": { "DEERDAWN_API_URL": "https://api.deerdawn.com" } } } } } ``` For **Continue** (`~/.continue/config.json`): ```json { "mcpServers": [ { "name": "deerdawn", "command": "npx", "args": ["-y", "@deerdawn/mcp-server@latest"], "env": { "DEERDAWN_API_URL": "https://api.deerdawn.com" } } ] } ``` --- ### Zed Add to `~/.config/zed/settings.json`: ```json { "context_servers": { "deerdawn": { "command": { "path": "npx", "args": ["-y", "@deerdawn/mcp-server@latest"], "env": { "DEERDAWN_API_URL": "https://api.deerdawn.com" } } } } } ``` --- ### Codex (OpenAI) Add to `~/.codex/config.toml`: ```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" ``` --- To skip browser sign-in in any of these configs, add `"DEERDAWN_API_KEY": "dd_your_key_here"` to the `env` block (Codex TOML: `DEERDAWN_API_KEY = "dd_your_key_here"` under `[mcp_servers.deerdawn.env]`). --- ## Host naming note Some MCP hosts expose tools with a server prefix (for example `deerdawn-get_auth_status`) instead of bare names (`get_auth_status`). If a tool name is not found, retry with the `deerdawn-` prefixed variant. --- ## Environment variables All optional. With no env vars at all, the server starts and walks you through browser sign-in. | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `DEERDAWN_API_URL` | No | `https://api.deerdawn.com` | API base URL. Only change for self-hosted or staging. | | `DEERDAWN_SURFACE_ID` | No | auto-detected | Which tool this server runs in (`claude_code`, `cursor`, `codex`). Detected from the MCP client when unset; set it explicitly to pin session attribution. | | `DEERDAWN_API_KEY` | No | β€” | API key (`dd_...`) for non-interactive auth (CI/headless). Default is browser OAuth sign-in. Get one at app.deerdawn.com β†’ Settings β†’ API Keys. | --- ## Session memory tools The local server exposes 35 tools (the hosted remote exposes 18 core ones). These are the ones to reach for in every session. ### `start_session` **Call this at the start of every session.** Returns the active project context for the current directory plus a compact map of all other projects β€” one API call, ~100–180 tokens total. Do not call `list_context_map` + `get_context` separately; this replaces both. ### `update_context` Push a context update. **Call this whenever**: a decision is made, the current task changes, a blocker is found, or meaningful progress happens. Don't wait until the end of the session β€” updates are cheap and keep the brief every new session reads current. ``` 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` Get project context by section. Defaults to `[task, status]` (~30 tokens). Pass `sections=["all"]` for everything. ``` project_id: "proj-abc123" sections: ["task", "decisions", "blocking"] ``` ### `import_local_context` Import context from `CLAUDE.md`, `AGENTS.md`, or `.cursorrules` in the current directory. **Call without `confirmed: true` first** β€” it shows a free preview of what would be imported. Then call again with `confirmed: true` to commit. ### `complete_setup` One-call setup fallback for brittle hosts: checks auth status, applies local setup for a surface, and runs `import_local_context` preview + confirmation if local files are found. Example: ``` complete_setup { "surface": "cursor" } ``` ### `cleanup_context` Clean up task state at handoff or finish time. Use this to mark the active task complete and clear open-task command history so the next agent sees clean state. When the task is clearly done and there are no unresolved questions, call this automatically with `complete_task=true` (no extra confirmation loop). ``` cleanup_context { "complete_task": true } ``` ### `search_context` Search across all projects. Examples: `"decisions about authentication"`, `"projects using PostgreSQL"`, `"what's blocking the billing work"`. ### `list_projects` List all projects with IDs and last-updated timestamps. Use this when you explicitly need a project index. For normal startup, prefer `start_session`. ### `create_project` Create a new project when starting something that has no existing project entry. --- ## Workspace knowledge tools ### `get_workspace_overview` Use `mode=startup` at the start of a session for a compact orientation brief. Use `mode=overview` when the user asks "what am I working on?" or wants a broader picture. ### `get_workspace_entities` Drill into typed workspace knowledge: decisions, tools, environments, capabilities. Filter by `types`, `query`, `status`, or `project_id`. ### `get_project_map` Return durable file-level project memory: hot paths, entrypoints, named surfaces, and debugging notes. Use this before repo-wide search when the path may already be known. ### `find_known_paths` Search DeerDawn’s durable path memory for queries like `"auth modal"` or `"signup route"` before using repo search. ### `get_next_best_context` Get ranked suggestions for what context to fetch next, given the current tool and working directory. ### `upsert_workspace_entities` Create or update durable workspace knowledge β€” tools, environments, architectural decisions, or capabilities that apply across multiple projects. ### `record_hot_paths` Write discovered file or folder paths back into DeerDawn so future sessions can orient without re-discovering them. ### `record_debug_finding` Store concise durable debugging findings, optionally tied to specific paths. --- ## How it works A fresh AI session knows nothing about your project β€” it would start cold. DeerDawn hands it the brief instead. ``` 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 ``` The brief is stored per-project. Critical decisions are flagged and always surface first, regardless of token budget. If sections are trimmed, you'll see exactly what was dropped and how to retrieve it. --- ## Verify installation After saving your config and restarting the agent, call `start_session` first: ``` start_session ``` If it returns your active project context, DeerDawn is already connected β€” you're done, skip the rest. (If you connected through the hosted remote / claude.ai connector rather than the local server, this is the normal path: `apply_setup` and `import_local_context` won't exist on that build and aren't needed β€” context loads automatically.) If `start_session` reports you're not authenticated, complete sign-in and seed context: ``` get_auth_status import_local_context import_local_context {"confirmed":true} start_session cleanup_context {"complete_task":true} ``` If your host prefixes tool names, use `deerdawn-get_auth_status` and `deerdawn-import_local_context` instead. If your host is flaky during setup, run `complete_setup {"surface":"claude_code"}` as a one-call fallback β€” it checks auth, applies surface setup automatically, and imports local context in a single call. `apply_setup` is called internally and does not need to be run manually. You should get back your active project context (or a prompt to import local context if it's a new workspace). If you get an error instead: - Call `get_auth_status` and finish browser sign-in via the returned URL (if you set `DEERDAWN_API_KEY` instead, confirm it starts with `dd_`) - Fully restart the agent (not just reload) - Check MCP logs: `~/Library/Logs/Claude/mcp*.log` (Claude Desktop) or equivalent --- ## Troubleshooting **DeerDawn tools don't appear in your agent** The server itself starts with zero env vars β€” a missing API key never prevents startup. If no DeerDawn tools show up: 1. Fully restart your editor after saving the config (not just reload) 2. Check MCP logs: - Claude Desktop: `~/Library/Logs/Claude/mcp*.log` - Cursor: View β†’ Output β†’ MCP - Windsurf: Help β†’ Toggle Developer Tools β†’ Console - VS Code: Output panel β†’ MCP - Zed: Help β†’ Toggle Dev Tools β†’ Console **Authentication error / not signed in** Call `get_auth_status` β€” it returns a browser sign-in URL. Open it, approve, then retry the tool call; setup completes automatically. If you set `DEERDAWN_API_KEY`, it must start with `dd_`. **Sign-in reports a rate limit (HTTP 429)** This happens after several quick restarts during setup. Wait a minute before retrying β€” re-running setup immediately will keep hitting the limit. **`start_session` returns no projects** Call `import_local_context` (without `confirmed: true` first) to seed context from a `CLAUDE.md` or `AGENTS.md` in your current directory. **Slow responses** The extraction pipeline runs on first import. Subsequent `start_session` calls are fast (cached context lookup, no LLM call unless something changed). --- ## Development ```bash npm install npm run build # compile TypeScript npm run dev # watch mode npm test # run tests npm run lint ``` --- ## License MIT