bvandeusenandClaude Opus 5.5
47d40bffd8
Milestone 544, step 6217 (follow-up to #1778, which rewrote features.md and api-reference.md in July but left architecture.md and configuration.md alone). - architecture.md, configuration.md, development.md: rewritten against the code. They still described Ollama, chat, SSE generation, voice, project summaries, image caching, Docker secrets that the compose files don't use, a raw-SQL migration convention the migrations no longer follow, a 27-entry migration list, CalVer YY.MM.DD.N tags and the removed infra/ files. - features.md: adds what shipped since July (spikes, claims, moments, rule versions and verification, lessons, reply shapes, snippets and the shape ledger, forge integration, family canon, design systems, retrieval tuning) and corrects the Settings tabs and keyboard shortcuts (g g is the graph). - api-reference.md: adds the endpoints for snippets, lessons, design systems, family canon, platforms, shared areas, retrieval, rule versions, relations and verification, forge connections, webhooks, scheduled backups and the newer plugin hooks. - api-keys-and-mcp.md: Settings tab is "MCP Access"; a plugin install section; the tool-family table matches the tools that exist. - design-system.md: the dated "decisions in progress" changelog (April PR log, chat/journal/calendar surfaces) becomes a short present-tense section; the stored design system is named as the authority. - sso-oauth.md: the app is Scribe, not "Fabled Assistant". - README: feature summary and doc table brought current. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
115 lines
5.1 KiB
Markdown
115 lines
5.1 KiB
Markdown
# API Keys and Scribe MCP
|
|
|
|
## API Keys
|
|
|
|
API keys let external tools access your Scribe data without a browser session. Each key is scoped to a single user — it can only access data that user owns or has been shared with them.
|
|
|
|
### Scopes
|
|
|
|
| Scope | Permissions |
|
|
|-------|-------------|
|
|
| `read` | GET endpoints only — list, search, fetch content |
|
|
| `write` | Full read + create, update, delete |
|
|
|
|
Admin-level operations (log access, user management) require a `write`-scoped key from an admin account.
|
|
|
|
### Creating a Key
|
|
|
|
1. Go to **Settings → MCP Access**
|
|
2. Enter a name (e.g. "Claude MCP", "Home Server")
|
|
3. Choose scope
|
|
4. Click **Generate Key**
|
|
5. Copy the key immediately — it is shown only once (the token is `fmcp_`-prefixed)
|
|
|
|
Paste the key into the `Authorization: Bearer <key>` header of your MCP client
|
|
config (see **Scribe MCP Server** below).
|
|
|
|
### Revoking a Key
|
|
|
|
Click **Revoke** next to the key in the keys table and confirm. Revoked keys are deleted immediately.
|
|
|
|
---
|
|
|
|
## Scribe MCP Server
|
|
|
|
Scribe exposes itself as a set of MCP tools that Claude (and other MCP clients)
|
|
can use to read and write your notes, tasks, projects, rulebooks, and more. The
|
|
server is **built into the app** — it is mounted as a streamable-HTTP endpoint
|
|
at **`/mcp`** on the running Scribe instance (`src/scribe/mcp/server.py`). There
|
|
is nothing to install: no wheel, no separate package, no CLI. You connect a
|
|
client straight to the URL with a Bearer token.
|
|
|
|
### Authentication
|
|
|
|
Authenticate with an API key generated from **Settings → MCP Access** (see above),
|
|
sent as `Authorization: Bearer fmcp_<key>`. A `read`-scoped key may call only the
|
|
read tools (`get_*`, `list_*`, `search`, `enter_project`, `retrieval_telemetry`);
|
|
any write/delete tool is rejected with `403`. The allow-list is explicit rather
|
|
than derived from the name — see `_READ_ONLY_TOOLS`, which is why the two reads
|
|
without a read-shaped name are spelled out here. A `write`-scoped key may call everything.
|
|
|
|
### Claude Code: the plugin (recommended)
|
|
|
|
The plugin connects the MCP server and adds the hooks and skills that put Scribe's records in front of Claude as it works. Install it from this repo:
|
|
|
|
```
|
|
/plugin marketplace add https://git.fabledsword.com/bvandeusen/FabledScribe.git
|
|
/plugin install scribe@scribe-plugin
|
|
```
|
|
|
|
It asks for your Scribe base URL, an API key (kept in your OS keychain) and, optionally, a project id. Settings → MCP Access shows the exact command for your instance. [`plugin/README.md`](../plugin/README.md) describes each hook.
|
|
|
|
### Claude Code without the plugin
|
|
|
|
Add a `.mcp.json` at the project root. The server `type` is `http` and the URL is
|
|
your instance's `/mcp` endpoint:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"scribe": {
|
|
"type": "http",
|
|
"url": "https://your-scribe-instance.example.com/mcp",
|
|
"headers": {
|
|
"Authorization": "Bearer fmcp_your-api-key"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Note: `.mcp.json` contains an API key and should be added to `.gitignore`.
|
|
|
|
### Claude Code (Global)
|
|
|
|
The same `mcpServers` block can live in `~/.claude.json` to make the server
|
|
available across all projects. A project-scoped `.mcp.json` takes precedence over
|
|
the global entry when both define the same server name — useful for pointing a
|
|
specific project at a dev instance or an admin key.
|
|
|
|
### Available Tools
|
|
|
|
There are well over a hundred tools and they change with the app, so the
|
|
registration in **`src/scribe/mcp/tools/`** is the reference. By family:
|
|
|
|
| Family | Examples | Purpose |
|
|
|--------|----------|---------|
|
|
| Notes | `create_note`, `get_note`, `update_note`, `create_records` | Knowledge, and several records that cite each other in one call |
|
|
| Tasks | `create_task`, `update_task`, `add_task_log` | Work, issues and spikes, and their logs |
|
|
| Projects / Milestones | `enter_project`, `start_planning`, `get_milestone` | Projects and their plans |
|
|
| Search / Recall | `search`, `what_might_apply`, `get_recent` | Recall by meaning, and the rules that may apply to an act |
|
|
| Systems | `create_system`, `list_system_records`, `map_system_to_canonical` | A project's areas |
|
|
| Rules | `create_rule`, `create_project_rule`, `relate_rules`, `rule_history`, `list_moments` | Rules, preferences, their relations and moments |
|
|
| Lessons | `create_lesson`, `judge_lesson_link` | Lessons and the rules they instance |
|
|
| Snippets / Shapes | `create_snippet`, `verify_snippet`, `classify_shapes`, `list_shapes` | Prior art and the shape ledger |
|
|
| Design systems | `resolve_design_system`, `get_design_system_stylesheet` | Tokens and guidance for UI work |
|
|
| Family canon | `list_family_ideas`, `assess_family_adoption` | Ideas shared across projects |
|
|
| Processes | `list_processes`, `get_process`, `create_process` | Stored procedures |
|
|
| Retrieval | `retrieval_telemetry`, `tune_retrieval` | What was surfaced, and the thresholds |
|
|
| Trash | `list_trash`, `restore`, `purge_trash` | Recoverable deletes |
|
|
|
|
Server-level usage guidance — when to reach for each entity, the
|
|
recall-before-acting reflex, and the rulebook conventions — is delivered to the
|
|
client automatically via the MCP server's `instructions` block (defined in
|
|
`src/scribe/mcp/server.py`).
|