Home A - Z
Page Index

Blame

322cec Claude (Dev) 2026-03-13 01:48:19
[mcp] Port original PRD overview section to wiki
1 
---
2
category: reference
3
tags: [meta, design, prd]
4
last_updated: 2026-03-12
5
confidence: high
6
---
7
8
# Original PRD Overview
9
10
> This page is part of the original single-tenant PRD, split across five wiki pages:
ada4de Claude (MCP) 2026-03-13 17:49:50
[mcp] Normalize spaces to underscores
11
> [[Design/Research_Wiki]] | [[Design/Rest Api]] | [[Design/Semantic_Search]] | [[Design/Mcp Server]] | [[Design/Note_Schema]]
322cec Claude (Dev) 2026-03-13 01:48:19
[mcp] Port original PRD overview section to wiki
12
13
---
14
15
## Overview
16
17
Build a research knowledge base system that gives both a human (via web browser) and an AI assistant (via MCP over Claude.ai) full read/write access to a shared wiki. The wiki stores short, atomic, cross-linked markdown notes that serve as a living analytical framework for ongoing research.
18
19
The system has three components built on top of an existing Otterwiki fork:
20
21
1. **REST API plugin** for Otterwiki — programmatic CRUD on wiki pages
22
2. **Chroma semantic search plugin** for Otterwiki — vector index maintained in sync with page saves/deletes
23
3. **MCP server** — exposes wiki operations as MCP tools over SSE, connecting to Claude.ai
24
25
All three deploy together via docker-compose alongside Otterwiki itself.
26
27
---
28
29
## Context
30
31
### What is Otterwiki?
32
33
[Otterwiki](https://github.com/redimp/otterwiki) is a minimalistic, self-hosted wiki powered by Python, Flask, Markdown, and Git. Pages are stored as markdown files in a bare Git repository. It has a plugin system that loads from `/plugins` and `/app-data/plugins`.
34
35
### Why this system?
36
37
We currently maintain analytical research documents as PDFs in a Claude.ai project. This is clunky: PDFs are write-once, can't be cross-referenced programmatically, and are expensive to ingest. Decomposing the analysis into atomic wiki notes lets the AI pull only what's relevant per session, and both human and AI can maintain the knowledge base over time.
38
39
### Key users
40
41
- **Human researcher** — browses, edits, and organizes notes via Otterwiki's web UI
42
- **Claude AI assistant** — reads, writes, searches, and cross-references notes via MCP tools in Claude.ai
43
44
---
45
46
## Architecture
47
48
```
49
┌─────────────┐ ┌──────────────────────────────────────────────┐
50
│ Claude.ai │────▶│ MCP Server (SSE) │
51
│ (iOS/Web) │◀────│ Python / FastMCP │
52
└─────────────┘ │ Translates MCP tool calls → HTTP API calls │
53
└──────────────┬───────────────────────────────┘
54
│ HTTP
55
┌──────────────▼───────────────────────────────┐
56
│ Otterwiki (Flask) │
57
│ ┌─────────────────┐ ┌────────────────────┐ │
58
│ │ REST API Plugin │ │ Chroma Plugin │ │
59
│ │ /api/v1/* │ │ Vector index sync │ │
60
│ │ JSON CRUD │ │ Semantic search │ │
61
│ └────────┬────────┘ └────────┬───────────┘ │
62
│ │ │ │
63
│ ┌────────▼─────────────────────▼───────────┐ │
64
│ │ Otterwiki Core (Page, PageIndex, etc.) │ │
65
│ └────────┬─────────────────────────────────┘ │
66
│ │ │
67
│ ┌────────▼──────┐ ┌───────────────────┐ │
68
│ │ Git Repo │ │ Chroma DB │ │
69
│ │ (markdown) │ │ (vector index) │ │
70
│ └───────────────┘ └───────────────────┘ │
71
└──────────────────────────────────────────────┘
72
▲
73
┌──────────────┘
74
│ HTTP (browser)
75
┌─────┴─────┐
76
│ Human │
77
│ Browser │
78
└───────────┘
79
```
80
81
### Deployment
82
83
Single docker-compose stack:
84
85
- `otterwiki` — Otterwiki with plugins mounted
86
- `chromadb` — Chroma vector database (persistent volume)
87
- `mcp-server` — MCP SSE server
88
89
All on the same Docker network. The MCP server and Otterwiki communicate over internal HTTP. Only the MCP server's SSE endpoint and Otterwiki's web UI are exposed externally (behind a reverse proxy with TLS).
90
91
---
92
93
## Docker Compose
94
95
```yaml
96
services:
97
otterwiki:
98
image: redimp/otterwiki:2
99
# OR build from fork if modifying core:
100
# build: ./otterwiki
101
restart: unless-stopped
102
ports:
103
- "8080:80"
104
volumes:
105
- wiki-data:/app-data
106
- ./plugins:/app-data/plugins
107
environment:
108
OTTERWIKI_API_KEY: "${OTTERWIKI_API_KEY}"
109
CHROMADB_HOST: "chromadb"
110
CHROMADB_PORT: "8000"
111
112
chromadb:
113
image: chromadb/chroma:latest
114
restart: unless-stopped
115
volumes:
116
- chroma-data:/chroma/chroma
117
ports:
118
- "8000:8000"
119
120
mcp-server:
121
build: ./mcp-server
122
restart: unless-stopped
123
ports:
124
- "8090:8090"
125
environment:
126
OTTERWIKI_API_URL: "http://otterwiki:80"
127
OTTERWIKI_API_KEY: "${OTTERWIKI_API_KEY}"
128
MCP_PORT: "8090"
129
130
volumes:
131
wiki-data:
132
chroma-data:
133
```
134
135
---
136
137
## Implementation Sequence
138
139
### Phase 1: Investigate plugin system (30 min)
140
141
1. Read `otterwiki/plugins.py` in the fork
142
2. Read `docs/plugin_examples/`
143
3. Determine: Can plugins register Flask blueprints? What hooks are available?
144
4. Decision: plugin path vs. core modification path
145
146
### Phase 2: REST API (core deliverable)
147
148
1. Implement the API endpoints (blueprint or plugin, per Phase 1 findings)
149
2. API key authentication middleware
150
3. WikiLink parsing and link graph
151
4. Test with curl
152
153
### Phase 3: Chroma integration
154
155
1. Add ChromaDB client to the Otterwiki environment
156
2. Implement index sync (hook-based or periodic, per Phase 1 findings)
157
3. Add semantic search endpoint
158
4. Add `/reindex` endpoint for bulk population
159
5. Test semantic search
160
161
### Phase 4: MCP server
162
163
1. Scaffold FastMCP server with SSE transport
164
2. Implement all eight tools as HTTP wrappers
165
3. Test locally with MCP inspector
166
4. Configure for docker-compose deployment
167
168
### Phase 5: Docker compose and deployment
169
170
1. Finalize docker-compose.yaml
171
2. Reverse proxy configuration (Caddy or Nginx)
172
3. TLS setup
173
4. Test end-to-end: Claude.ai → MCP → API → Otterwiki → Git
174
175
---
176
177
## Success Criteria
178
179
1. From Claude.ai, I can `read_note("Actors/Iran")` and get the page content with frontmatter and links
180
2. From Claude.ai, I can `write_note("Events/2026-03-09 Day 10", content)` and it appears in Otterwiki's web UI within seconds
181
3. From Claude.ai, I can `semantic_search("interceptor depletion strategy")` and get relevant notes even if they don't contain those exact words
182
4. From the Otterwiki web UI, I can edit a note and the changes are reflected in subsequent MCP tool calls
183
5. All changes are Git-committed with meaningful messages and full version history
184
6. The Chroma index stays in sync with the wiki content regardless of whether edits come from the API or the web UI