{
  "markdown": "# DeerDawn MCP Server\n\nNever start cold. Every new AI session opens already briefed on your project.\n\nDeerDawn 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.\n\n> **About this repository.** DeerDawn is a hosted service. This repo holds the\n> public install guide, the `server.json` manifest published to the MCP registry,\n> and a Dockerfile that launches the published npm package. The server itself\n> ships from npm as [`@deerdawn/mcp-server`](https://www.npmjs.com/package/@deerdawn/mcp-server);\n> its source is not open. Issues and questions are welcome here.\n\n## Quick start — hosted server (recommended, no install)\n\nConnect to the hosted MCP endpoint. **No API key needed** — you sign in with your browser the first time a DeerDawn tool is called.\n\n**Claude Code**\n\n```bash\nclaude mcp add -s user --transport http deerdawn https://api.deerdawn.com/api/v1/mcp\n```\n\n**Every other tool** — add a remote MCP server (sometimes called a connector) with this URL:\n\n```\nhttps://api.deerdawn.com/api/v1/mcp\n```\n\n| Tool | Where |\n|------|-------|\n| Claude.ai | Settings → Connectors → Add custom connector |\n| ChatGPT.com | Settings → Connectors → Add MCP server (choose OAuth) |\n| Cursor | Settings → MCP → Add server, or add a `\"url\"` entry in `.cursor/mcp.json` |\n| VS Code / Copilot | Command palette → MCP: Add Server → HTTP → paste the URL |\n| Windsurf, Gemini, others | Add a custom remote / HTTP MCP server with the URL |\n\nLeave 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.\n\nThen say: **\"Start a DeerDawn session.\"**\n\nThe 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.\n\n---\n\n## Local install (stdio) — optional upgrade\n\nRun the server on your machine via `npx -y @deerdawn/mcp-server@latest` when you want deeper integration:\n\n- Writes `.deerdawn-context.md` / `.cursorrules` into your repo so context loads with no tool call.\n- Installs SessionStart / Stop hooks that capture and flush context automatically.\n- Exposes the full set of 35 tools (the hosted server exposes 18 core ones).\n\n**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.\n\n**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.\n\n### Claude Code (CLI)\n\nRun the setup command — it registers the server, signs you in, and configures hooks in one step:\n\n```bash\nnpx -y @deerdawn/mcp-server@latest setup\n```\n\nOr register manually (user scope so it works across all projects):\n\n```bash\nclaude 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\n```\n\nRestart Claude Code after registering. If you haven't signed in yet, call `get_auth_status` — it returns the browser URL to complete sign-in.\n\n---\n\n### Claude Desktop\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"deerdawn\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@deerdawn/mcp-server@latest\"],\n      \"env\": {\n        \"DEERDAWN_API_URL\": \"https://api.deerdawn.com\"\n      }\n    }\n  }\n}\n```\n\n---\n\n### Cursor\n\n`~/.cursor/mcp.json` (same path on macOS, Linux, and Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"deerdawn\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@deerdawn/mcp-server@latest\"],\n      \"env\": {\n        \"DEERDAWN_API_URL\": \"https://api.deerdawn.com\"\n      }\n    }\n  }\n}\n```\n\n---\n\n### Windsurf\n\n**macOS**: `~/.codeium/windsurf/mcp_config.json`\n**Windows**: `%APPDATA%\\Codeium\\windsurf\\mcp_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"deerdawn\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@deerdawn/mcp-server@latest\"],\n      \"env\": {\n        \"DEERDAWN_API_URL\": \"https://api.deerdawn.com\"\n      }\n    }\n  }\n}\n```\n\n---\n\n### VS Code (GitHub Copilot / Continue)\n\nAdd to `.vscode/settings.json` or user `settings.json`:\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"deerdawn\": {\n        \"command\": \"npx\",\n        \"args\": [\"-y\", \"@deerdawn/mcp-server@latest\"],\n        \"env\": {\n          \"DEERDAWN_API_URL\": \"https://api.deerdawn.com\"\n        }\n      }\n    }\n  }\n}\n```\n\nFor **Continue** (`~/.continue/config.json`):\n\n```json\n{\n  \"mcpServers\": [\n    {\n      \"name\": \"deerdawn\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@deerdawn/mcp-server@latest\"],\n      \"env\": {\n        \"DEERDAWN_API_URL\": \"https://api.deerdawn.com\"\n      }\n    }\n  ]\n}\n```\n\n---\n\n### Zed\n\nAdd to `~/.config/zed/settings.json`:\n\n```json\n{\n  \"context_servers\": {\n    \"deerdawn\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"-y\", \"@deerdawn/mcp-server@latest\"],\n        \"env\": {\n          \"DEERDAWN_API_URL\": \"https://api.deerdawn.com\"\n        }\n      }\n    }\n  }\n}\n```\n\n---\n\n### Codex (OpenAI)\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.deerdawn]\ncommand = \"npx\"\nargs = [\"-y\", \"@deerdawn/mcp-server@latest\"]\nstartup_timeout_sec = 120\n\n[mcp_servers.deerdawn.env]\nDEERDAWN_API_URL = \"https://api.deerdawn.com\"\n```\n\n---\n\nTo 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]`).\n\n---\n\n## Host naming note\n\nSome MCP hosts expose tools with a server prefix (for example `deerdawn-get_auth_status`) instead of bare names (`get_auth_status`).\nIf a tool name is not found, retry with the `deerdawn-` prefixed variant.\n\n---\n\n## Environment variables\n\nAll optional. With no env vars at all, the server starts and walks you through browser sign-in.\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `DEERDAWN_API_URL` | No | `https://api.deerdawn.com` | API base URL. Only change for self-hosted or staging. |\n| `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. |\n| `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. |\n\n---\n\n## Session memory tools\n\nThe local server exposes 35 tools (the hosted remote exposes 18 core ones). These are the ones to reach for in every session.\n\n### `start_session`\n**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.\n\n### `update_context`\nPush 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.\n\n```\nproject_id: \"proj-abc123\"\nsummary: \"Switched auth from JWT to session tokens — JWT had XSS risk via localStorage. Now using Redis-backed sessions.\"\n```\n\n### `get_context`\nGet project context by section. Defaults to `[task, status]` (~30 tokens). Pass `sections=[\"all\"]` for everything.\n\n```\nproject_id: \"proj-abc123\"\nsections: [\"task\", \"decisions\", \"blocking\"]\n```\n\n### `import_local_context`\nImport 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.\n\n### `complete_setup`\nOne-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.\n\nExample:\n\n```\ncomplete_setup\n{\n  \"surface\": \"cursor\"\n}\n```\n\n### `cleanup_context`\nClean 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.\n\nWhen the task is clearly done and there are no unresolved questions, call this automatically with `complete_task=true` (no extra confirmation loop).\n\n```\ncleanup_context\n{\n  \"complete_task\": true\n}\n```\n\n### `search_context`\nSearch across all projects. Examples: `\"decisions about authentication\"`, `\"projects using PostgreSQL\"`, `\"what's blocking the billing work\"`.\n\n### `list_projects`\nList all projects with IDs and last-updated timestamps. Use this when you explicitly need a project index. For normal startup, prefer `start_session`.\n\n### `create_project`\nCreate a new project when starting something that has no existing project entry.\n\n---\n\n## Workspace knowledge tools\n\n### `get_workspace_overview`\nUse `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.\n\n### `get_workspace_entities`\nDrill into typed workspace knowledge: decisions, tools, environments, capabilities. Filter by `types`, `query`, `status`, or `project_id`.\n\n### `get_project_map`\nReturn 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.\n\n### `find_known_paths`\nSearch DeerDawn’s durable path memory for queries like `\"auth modal\"` or `\"signup route\"` before using repo search.\n\n### `get_next_best_context`\nGet ranked suggestions for what context to fetch next, given the current tool and working directory.\n\n### `upsert_workspace_entities`\nCreate or update durable workspace knowledge — tools, environments, architectural decisions, or capabilities that apply across multiple projects.\n\n### `record_hot_paths`\nWrite discovered file or folder paths back into DeerDawn so future sessions can orient without re-discovering them.\n\n### `record_debug_finding`\nStore concise durable debugging findings, optionally tied to specific paths.\n\n---\n\n## How it works\n\nA fresh AI session knows nothing about your project — it would start cold. DeerDawn hands it the brief instead.\n\n```\nYou work in Claude Code, Cursor, or ChatGPT\n  → DeerDawn captures the session (via MCP, browser extension, or desktop app)\n  → Extraction pipeline distills what changed (task, decisions, blockers, stack) into the brief\n  → The brief is stored per-project in your workspace and kept current\n  → Next session would start cold — instead start_session hands it the brief in one call\n  → Every new session opens already briefed, never from a blank slate\n```\n\nThe 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.\n\n---\n\n## Verify installation\n\nAfter saving your config and restarting the agent, call `start_session` first:\n\n```\nstart_session\n```\n\nIf 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.)\n\nIf `start_session` reports you're not authenticated, complete sign-in and seed context:\n\n```\nget_auth_status\nimport_local_context\nimport_local_context {\"confirmed\":true}\nstart_session\ncleanup_context {\"complete_task\":true}\n```\n\nIf your host prefixes tool names, use `deerdawn-get_auth_status` and `deerdawn-import_local_context` instead.\n\nIf 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.\n\nYou 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:\n\n- 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_`)\n- Fully restart the agent (not just reload)\n- Check MCP logs: `~/Library/Logs/Claude/mcp*.log` (Claude Desktop) or equivalent\n\n---\n\n## Troubleshooting\n\n**DeerDawn tools don't appear in your agent**\nThe server itself starts with zero env vars — a missing API key never prevents startup. If no DeerDawn tools show up:\n1. Fully restart your editor after saving the config (not just reload)\n2. Check MCP logs:\n   - Claude Desktop: `~/Library/Logs/Claude/mcp*.log`\n   - Cursor: View → Output → MCP\n   - Windsurf: Help → Toggle Developer Tools → Console\n   - VS Code: Output panel → MCP\n   - Zed: Help → Toggle Dev Tools → Console\n\n**Authentication error / not signed in**\nCall `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_`.\n\n**Sign-in reports a rate limit (HTTP 429)**\nThis happens after several quick restarts during setup. Wait a minute before retrying — re-running setup immediately will keep hitting the limit.\n\n**`start_session` returns no projects**\nCall `import_local_context` (without `confirmed: true` first) to seed context from a `CLAUDE.md` or `AGENTS.md` in your current directory.\n\n**Slow responses**\nThe extraction pipeline runs on first import. Subsequent `start_session` calls are fast (cached context lookup, no LLM call unless something changed).\n\n---\n\n## Development\n\n```bash\nnpm install\nnpm run build   # compile TypeScript\nnpm run dev     # watch mode\nnpm test        # run tests\nnpm run lint\n```\n\n---\n\n## License\n\nMIT\n",
  "bytes": 14772,
  "sha": "6f4cece36b42b00d0d3c633ebf4f0ab121e4f588361fa407c753fe6912927b25",
  "repo_slug": "hissingspider/deerdawn-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_deerdawn_deerdawn_ac9425b7/readme"
}