com.deerdawn/deerdawn

AI session memory: the brief your AI reads before every session so no session starts cold.

Open source Repository Open in the app JSON README (API)

About

AI session memory: the brief your AI reads before every session so no session starts cold.

Details

Kind

MCP servers

Topic

AI, RAG & memory

Publisher

com.deerdawn

Origin

official

Category

ferramentas

Transport

http

Version

1.0.42

Last push

2026-08-14T07:11:58Z

Repository state

ativo

Language

Dockerfile

License

MIT

Added

2026-08-29 03:01:05

Updated

2026-08-29 03:01:05

Origin id

com.deerdawn/deerdawn

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

More

• More mcp servers on AI, RAG & memory
• Everything published by com.deerdawn
• Browse the whole catalog