deerdawn-mcp

# 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