docs: restructure documentation into docs/ directory, slim README, add project .mcp.json
- README.md: reduced to overview + quick start + links to docs/ - docs/architecture.md: stack, design decisions, data models, key services - docs/configuration.md: all env vars, docker-compose setup, production + security - docs/development.md: dev workflow, CI/CD, migrations, release process - docs/features.md: detailed feature breakdown + keyboard shortcuts - docs/api-keys-and-mcp.md: API key management + Fable MCP install guide - docs/sso-oauth.md: OAuth/OIDC setup (replaces docs/oauth-setup.md) - docs/changelog.md: development history from summary.md - Remove summary.md (content distributed across docs/) - Remove docs/oauth-setup.md (superseded by docs/sso-oauth.md) - .gitignore: add .mcp.json Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,144 @@
|
||||
# API Keys and Fable MCP
|
||||
|
||||
## API Keys
|
||||
|
||||
API keys let external tools access your Fable 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 → API Keys**
|
||||
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
|
||||
|
||||
After creation you can download:
|
||||
- **`.env` file** — `FABLE_URL` + `FABLE_API_KEY` ready to paste
|
||||
- **Claude config JSON** — `mcpServers` block ready to merge into `~/.claude.json`
|
||||
|
||||
### Revoking a Key
|
||||
|
||||
Click **Revoke** next to the key in the API Keys table and confirm. Revoked keys are deleted immediately.
|
||||
|
||||
---
|
||||
|
||||
## Fable MCP Server
|
||||
|
||||
The Fable MCP server (`fable-mcp`) exposes Fable as a set of MCP tools that Claude (and other MCP clients) can use to read and write your notes, tasks, projects, and more.
|
||||
|
||||
### Download
|
||||
|
||||
The wheel is bundled into the Docker image at build time and available for download from **Settings → API Keys → Fable MCP** when you are logged in.
|
||||
|
||||
You can also download it directly:
|
||||
```
|
||||
GET /api/fable-mcp/download
|
||||
```
|
||||
(Requires login — authenticated browser session or API key in `Authorization: Bearer <key>` header.)
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Install the wheel
|
||||
pip install fable_mcp-*.whl
|
||||
|
||||
# Verify
|
||||
fable-mcp --help
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
The server reads two environment variables:
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `FABLE_URL` | Base URL of your Fable instance (e.g. `https://notes.example.com`) |
|
||||
| `FABLE_API_KEY` | API key generated from Settings → API Keys |
|
||||
|
||||
Create a `.env` file in your working directory, or set them in your shell / MCP config.
|
||||
|
||||
### Claude Code (Global)
|
||||
|
||||
Add to `~/.claude.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"fable": {
|
||||
"type": "stdio",
|
||||
"command": "fable-mcp",
|
||||
"env": {
|
||||
"FABLE_URL": "https://your-fable-instance.example.com",
|
||||
"FABLE_API_KEY": "your-api-key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Claude Code (Project-scoped)
|
||||
|
||||
Add a `.mcp.json` at the project root (same format as the global config). Project-scoped config takes precedence over global when the same server name is defined in both. This is useful for using a dev instance or admin key within a specific project.
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"fable": {
|
||||
"type": "stdio",
|
||||
"command": "fable-mcp",
|
||||
"env": {
|
||||
"FABLE_URL": "http://localhost:5000",
|
||||
"FABLE_API_KEY": "your-dev-api-key"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Note: `.mcp.json` contains an API key and should be added to `.gitignore`.
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `fable_list_notes` | List notes, filter by tag or search text |
|
||||
| `fable_get_note` | Fetch a note by ID |
|
||||
| `fable_create_note` | Create a new note |
|
||||
| `fable_update_note` | Update a note |
|
||||
| `fable_delete_note` | Delete a note |
|
||||
| `fable_list_tasks` | List tasks, filter by status or project |
|
||||
| `fable_get_task` | Fetch a task by ID |
|
||||
| `fable_create_task` | Create a new task |
|
||||
| `fable_update_task` | Update a task |
|
||||
| `fable_add_task_log` | Append a work log entry to a task |
|
||||
| `fable_list_projects` | List all projects |
|
||||
| `fable_get_project` | Fetch a project with milestone summary |
|
||||
| `fable_create_project` | Create a project |
|
||||
| `fable_update_project` | Update a project |
|
||||
| `fable_list_milestones` | List milestones for a project |
|
||||
| `fable_create_milestone` | Create a milestone |
|
||||
| `fable_update_milestone` | Update a milestone |
|
||||
| `fable_search` | Semantic search over notes and tasks |
|
||||
| `fable_list_conversations` | List MCP chat conversations |
|
||||
| `fable_send_message` | Send a message to Fable's LLM |
|
||||
| `fable_get_app_logs` | Fetch application logs (admin key required) |
|
||||
|
||||
### Development Notes
|
||||
|
||||
The `fable-mcp` package lives in `fable-mcp/` in this repository. The Docker build compiles it into a wheel at `/app/dist/` so it can be served for download without requiring the source tree at runtime.
|
||||
|
||||
To build the wheel locally:
|
||||
```bash
|
||||
cd fable-mcp
|
||||
pip install build hatchling
|
||||
python -m build --wheel .
|
||||
```
|
||||
Reference in New Issue
Block a user