@agent-wiki/mcp-server 0.3.0 → 0.3.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +100 -103
- package/package.json +5 -2
package/README.md
CHANGED
|
@@ -1,25 +1,26 @@
|
|
|
1
1
|
# agent-wiki
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/@agent-wiki/mcp-server)
|
|
3
4
|
[](https://github.com/xinhuagu/agent-wiki/actions/workflows/ci.yml)
|
|
4
5
|
[](https://nodejs.org)
|
|
5
6
|
[](https://modelcontextprotocol.io)
|
|
6
7
|
[](LICENSE)
|
|
7
8
|
|
|
8
|
-
A structured knowledge base that any AI agent can read, write, and maintain through the [Model Context Protocol](https://modelcontextprotocol.io). No LLM built in — your agent IS the
|
|
9
|
+
A structured knowledge base that any AI agent can read, write, and maintain through the [Model Context Protocol](https://modelcontextprotocol.io). No LLM built in — your agent IS the intelligence.
|
|
9
10
|
|
|
10
11
|
```
|
|
11
|
-
npx @agent-wiki/mcp-server
|
|
12
|
+
npx @agent-wiki/mcp-server serve --wiki-path ./my-knowledge
|
|
12
13
|
```
|
|
13
14
|
|
|
14
15
|
---
|
|
15
16
|
|
|
16
|
-
##
|
|
17
|
+
## Why
|
|
17
18
|
|
|
18
|
-
Most AI systems treat knowledge as disposable. You ask a question, it retrieves some fragments, generates an answer, and everything is forgotten. Next time
|
|
19
|
+
Most AI systems treat knowledge as disposable. You ask a question, it retrieves some fragments, generates an answer, and everything is forgotten. Next time, it starts from zero.
|
|
19
20
|
|
|
20
|
-
agent-wiki takes a different approach: **knowledge compilation
|
|
21
|
+
agent-wiki takes a different approach: **knowledge compilation**, a concept introduced by [Andrej Karpathy](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Instead of retrieving raw documents every time (RAG), the agent incrementally builds and maintains a persistent wiki — structured, interlinked, and continuously refined. Every interaction makes the knowledge base better.
|
|
21
22
|
|
|
22
|
-
The key insight: **LLMs are better editors than search engines.** Let them curate, synthesize, and maintain knowledge over time
|
|
23
|
+
The key insight: **LLMs are better editors than search engines.** Let them curate, synthesize, and maintain knowledge over time — not just retrieve it on demand.
|
|
23
24
|
|
|
24
25
|
### RAG vs Knowledge Compilation
|
|
25
26
|
|
|
@@ -30,50 +31,93 @@ The key insight: **LLMs are better editors than search engines.** Let them curat
|
|
|
30
31
|
| **Quality** | Raw chunks, often noisy | Curated, structured, interlinked |
|
|
31
32
|
| **Cost** | Embedding + retrieval every query | One-time compilation, free reads |
|
|
32
33
|
| **Contradictions** | Invisible — buried in source docs | Detected automatically by lint |
|
|
33
|
-
| **Source tracking** | Lost after retrieval | Full provenance chain (raw
|
|
34
|
+
| **Source tracking** | Lost after retrieval | Full provenance chain (raw → wiki) |
|
|
34
35
|
|
|
35
36
|
## Architecture
|
|
36
37
|
|
|
37
38
|
Three immutability layers, inspired by how compilers work:
|
|
38
39
|
|
|
40
|
+
| Layer | Mutability | Role |
|
|
41
|
+
|-------|-----------|------|
|
|
42
|
+
| **raw/** | Immutable | Source documents — write-once, SHA-256 verified. Papers, articles, web pages. |
|
|
43
|
+
| **wiki/** | Mutable | Compiled knowledge — structured Markdown pages that improve over time. |
|
|
44
|
+
| **schemas/** | Reference | Entity templates — consistent structure across 9 knowledge types. |
|
|
45
|
+
|
|
46
|
+
The agent reads from `raw/`, compiles understanding into `wiki/`, and the lint engine ensures quality:
|
|
47
|
+
|
|
48
|
+
<p align="center">
|
|
49
|
+
<img src="architecture.svg" alt="agent-wiki architecture" width="700" />
|
|
50
|
+
</p>
|
|
51
|
+
|
|
52
|
+
## Quick Start
|
|
53
|
+
|
|
54
|
+
### Claude Code / AceClaw
|
|
55
|
+
|
|
56
|
+
```json
|
|
57
|
+
{
|
|
58
|
+
"mcpServers": {
|
|
59
|
+
"agent-wiki": {
|
|
60
|
+
"command": "npx",
|
|
61
|
+
"args": ["-y", "@agent-wiki/mcp-server", "serve", "--wiki-path", "/path/to/knowledge"]
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Cursor / Windsurf / any MCP client
|
|
68
|
+
|
|
69
|
+
Same pattern — point your MCP config to:
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
npx -y @agent-wiki/mcp-server serve --wiki-path /path/to/knowledge
|
|
39
73
|
```
|
|
40
|
-
raw/ Immutable source documents (write-once, SHA-256 verified)
|
|
41
|
-
Papers, articles, web pages — the "source code" of knowledge
|
|
42
74
|
|
|
43
|
-
|
|
44
|
-
|
|
75
|
+
### Claude Desktop
|
|
76
|
+
|
|
77
|
+
`claude_desktop_config.json`:
|
|
45
78
|
|
|
46
|
-
|
|
47
|
-
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"mcpServers": {
|
|
82
|
+
"agent-wiki": {
|
|
83
|
+
"command": "npx",
|
|
84
|
+
"args": ["-y", "@agent-wiki/mcp-server", "serve", "--wiki-path", "/path/to/knowledge"]
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
48
88
|
```
|
|
49
89
|
|
|
50
|
-
|
|
90
|
+
### Workspace Separation
|
|
51
91
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
92
|
+
Code and data live in separate directories. The tool is stateless — all state lives in the workspace:
|
|
93
|
+
|
|
94
|
+
```
|
|
95
|
+
npx @agent-wiki/mcp-server serve --wiki-path ./config --workspace ./data
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Resolution priority: CLI `--workspace` > `AGENT_WIKI_WORKSPACE` env > config file > config root.
|
|
55
99
|
|
|
56
|
-
##
|
|
100
|
+
## Features
|
|
57
101
|
|
|
58
|
-
### Immutable Source Layer (
|
|
102
|
+
### Immutable Source Layer (raw/)
|
|
59
103
|
|
|
60
104
|
- **Write-once** — raw files can never be modified or overwritten after creation
|
|
61
|
-
- **SHA-256 integrity** — every file is hashed; corruption or tampering is detected
|
|
105
|
+
- **SHA-256 integrity** — every file is hashed; corruption or tampering is detected on `raw_verify`
|
|
62
106
|
- **Provenance tracking** — `.meta.yaml` sidecars record source URL, download time, description
|
|
63
|
-
- **URL fetching** — `raw_fetch` downloads
|
|
107
|
+
- **URL fetching** — `raw_fetch` downloads from URLs with smart arXiv handling (`arxiv.org/abs/XXXX` auto-converts to PDF)
|
|
64
108
|
- **Local file copy** — `raw_add` with `source_path` physically copies files into `raw/`
|
|
65
109
|
|
|
66
|
-
###
|
|
110
|
+
### Compiled Knowledge Layer (wiki/)
|
|
67
111
|
|
|
68
112
|
- **Structured Markdown** — YAML frontmatter (title, type, tags, sources) + Markdown body
|
|
69
113
|
- **9 entity types** — person, concept, event, artifact, comparison, summary, how-to, note, synthesis
|
|
70
|
-
- **Auto-classification** — heuristic classifier assigns entity type and suggests tags
|
|
71
|
-
-
|
|
72
|
-
- **Synthesis
|
|
114
|
+
- **Auto-classification** — heuristic classifier assigns entity type and suggests tags (zero LLM, zero latency)
|
|
115
|
+
- **Wiki-links** — `[[page]]` syntax to interlink pages and build a knowledge graph
|
|
116
|
+
- **Synthesis** — distill higher-order knowledge by combining multiple pages
|
|
73
117
|
- **Auto-timestamps** — `created` and `updated` managed automatically
|
|
74
118
|
- **System pages** — index.md, log.md, timeline.md maintained by the engine
|
|
75
119
|
|
|
76
|
-
### Self-Checking
|
|
120
|
+
### Self-Checking Lint Engine
|
|
77
121
|
|
|
78
122
|
No human review needed. The lint system catches problems automatically:
|
|
79
123
|
|
|
@@ -83,22 +127,7 @@ No human review needed. The lint system catches problems automatically:
|
|
|
83
127
|
- **Missing sources** — wiki claims not traceable to raw documents
|
|
84
128
|
- **Stale content** — pages not updated beyond a configurable threshold
|
|
85
129
|
- **Raw integrity** — SHA-256 re-verification of all source files
|
|
86
|
-
- **Synthesis integrity** — checks that source pages
|
|
87
|
-
|
|
88
|
-
### Workspace Separation
|
|
89
|
-
|
|
90
|
-
Code and data live in separate directories. The tool is stateless; all state lives in the workspace:
|
|
91
|
-
|
|
92
|
-
```yaml
|
|
93
|
-
# .agent-wiki.yaml
|
|
94
|
-
wiki:
|
|
95
|
-
workspace: /path/to/data # all data goes here
|
|
96
|
-
path: wiki/
|
|
97
|
-
raw_path: raw/
|
|
98
|
-
schemas_path: schemas/
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
Workspace resolution priority: CLI `--workspace` > `AGENT_WIKI_WORKSPACE` env > config file > config root.
|
|
130
|
+
- **Synthesis integrity** — checks that source pages still exist
|
|
102
131
|
|
|
103
132
|
### Auto-Classification
|
|
104
133
|
|
|
@@ -109,55 +138,19 @@ Input: "# YOLO Object Detection\n\nYOLO is a real-time detection model..."
|
|
|
109
138
|
Output: { type: "concept", tags: ["yolo", "object-detection", "real-time"], confidence: 0.8 }
|
|
110
139
|
```
|
|
111
140
|
|
|
112
|
-
Pure heuristic — no LLM calls, no API keys, zero latency. Supports English and Chinese
|
|
141
|
+
Pure heuristic — no LLM calls, no API keys, zero latency. Supports English and Chinese.
|
|
113
142
|
|
|
114
|
-
##
|
|
115
|
-
|
|
116
|
-
### Claude Code / AceClaw
|
|
117
|
-
|
|
118
|
-
`~/.aceclaw/mcp-servers.json`:
|
|
119
|
-
|
|
120
|
-
```json
|
|
121
|
-
{
|
|
122
|
-
"mcpServers": {
|
|
123
|
-
"agent-wiki": {
|
|
124
|
-
"command": "npx",
|
|
125
|
-
"args": ["-y", "agent-wiki", "serve", "--wiki-path", "/path/to/config", "--workspace", "/path/to/data"]
|
|
126
|
-
}
|
|
127
|
-
}
|
|
128
|
-
}
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
### Cursor / Windsurf / any MCP client
|
|
132
|
-
|
|
133
|
-
Same pattern — `npx -y @agent-wiki/mcp-server serve --wiki-path /path/to/config`.
|
|
134
|
-
|
|
135
|
-
### Claude Desktop
|
|
136
|
-
|
|
137
|
-
`claude_desktop_config.json`:
|
|
138
|
-
|
|
139
|
-
```json
|
|
140
|
-
{
|
|
141
|
-
"mcpServers": {
|
|
142
|
-
"agent-wiki": {
|
|
143
|
-
"command": "npx",
|
|
144
|
-
"args": ["-y", "agent-wiki", "serve", "--wiki-path", "/path/to/config"]
|
|
145
|
-
}
|
|
146
|
-
}
|
|
147
|
-
}
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
## MCP Tools (17 total)
|
|
143
|
+
## MCP Tools (19)
|
|
151
144
|
|
|
152
145
|
### Raw Layer — Immutable Sources
|
|
153
146
|
|
|
154
147
|
| Tool | Description |
|
|
155
148
|
|------|-------------|
|
|
156
|
-
| `raw_add` | Add a source document (
|
|
149
|
+
| `raw_add` | Add a source document (content string or local file copy, SHA-256 hashed, .meta.yaml sidecar) |
|
|
157
150
|
| `raw_fetch` | Download from URL to raw/ (smart arXiv handling, auto-provenance) |
|
|
158
|
-
| `raw_list` | List all raw documents with metadata |
|
|
151
|
+
| `raw_list` | List all raw documents with metadata (path, source URL, hash, size) |
|
|
159
152
|
| `raw_read` | Read a raw document's content and metadata |
|
|
160
|
-
| `raw_verify` | Verify integrity of all raw files
|
|
153
|
+
| `raw_verify` | Verify integrity of all raw files via SHA-256 re-check |
|
|
161
154
|
|
|
162
155
|
### Wiki Layer — Compiled Knowledge
|
|
163
156
|
|
|
@@ -166,24 +159,24 @@ Same pattern — `npx -y @agent-wiki/mcp-server serve --wiki-path /path/to/confi
|
|
|
166
159
|
| `wiki_read` | Read a page (frontmatter + Markdown) |
|
|
167
160
|
| `wiki_write` | Create or update a page (auto-timestamps, auto-classify) |
|
|
168
161
|
| `wiki_delete` | Delete a page (guards system pages) |
|
|
169
|
-
| `wiki_list` | List pages, filter by type or tag |
|
|
170
|
-
| `wiki_search` | Full-text keyword search with relevance scoring |
|
|
171
|
-
| `wiki_lint` | Health checks: contradictions, orphans, broken links, integrity |
|
|
162
|
+
| `wiki_list` | List pages, filter by entity type or tag |
|
|
163
|
+
| `wiki_search` | Full-text keyword search with relevance scoring and snippets |
|
|
172
164
|
| `wiki_classify` | Auto-classify content into entity type + suggest tags |
|
|
173
|
-
| `wiki_synthesize` | Prepare context for knowledge distillation across pages |
|
|
174
|
-
| `
|
|
175
|
-
| `
|
|
176
|
-
| `
|
|
177
|
-
| `
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
165
|
+
| `wiki_synthesize` | Prepare context for knowledge distillation across multiple pages |
|
|
166
|
+
| `wiki_lint` | Health checks: contradictions, orphans, broken links, integrity |
|
|
167
|
+
| `wiki_log` | View operation history with timestamps |
|
|
168
|
+
| `wiki_init` | Initialize a new knowledge base (creates wiki/, raw/, schemas/) |
|
|
169
|
+
| `wiki_config` | Show current workspace configuration and paths |
|
|
170
|
+
| `wiki_schemas` | List available entity templates |
|
|
171
|
+
| `wiki_rebuild_index` | Rebuild index.md organized by type with counts |
|
|
172
|
+
| `wiki_rebuild_timeline` | Rebuild timeline.md as a chronological view |
|
|
180
173
|
|
|
181
174
|
## Entity Types
|
|
182
175
|
|
|
183
176
|
| Type | Use Case | Example |
|
|
184
177
|
|------|----------|---------|
|
|
185
178
|
| `person` | People profiles | Researchers, engineers, historical figures |
|
|
186
|
-
| `concept` | Ideas and definitions | YOLO, attention mechanism,
|
|
179
|
+
| `concept` | Ideas and definitions | YOLO, attention mechanism, GIL |
|
|
187
180
|
| `event` | Things that happened | Conference talks, releases, incidents |
|
|
188
181
|
| `artifact` | Created things | Papers, tools, models, datasets |
|
|
189
182
|
| `comparison` | Side-by-side analysis | YOLOv8 vs YOLOv9, PyTorch vs TensorFlow |
|
|
@@ -224,15 +217,15 @@ derived_from: [concept-yolo.md, concept-ssd.md, concept-rcnn.md]
|
|
|
224
217
|
## CLI
|
|
225
218
|
|
|
226
219
|
```bash
|
|
227
|
-
npx agent-wiki serve
|
|
228
|
-
npx agent-wiki serve --workspace ./data
|
|
229
|
-
npx agent-wiki init ./my-kb
|
|
230
|
-
npx agent-wiki search "yolo"
|
|
231
|
-
npx agent-wiki list
|
|
232
|
-
npx agent-wiki list --type concept
|
|
233
|
-
npx agent-wiki raw-list
|
|
234
|
-
npx agent-wiki raw-verify
|
|
235
|
-
npx agent-wiki lint
|
|
220
|
+
npx @agent-wiki/mcp-server serve # start MCP server (stdio)
|
|
221
|
+
npx @agent-wiki/mcp-server serve --workspace ./data # separate data directory
|
|
222
|
+
npx @agent-wiki/mcp-server init ./my-kb # initialize new knowledge base
|
|
223
|
+
npx @agent-wiki/mcp-server search "yolo" # search wiki
|
|
224
|
+
npx @agent-wiki/mcp-server list # list all pages
|
|
225
|
+
npx @agent-wiki/mcp-server list --type concept # filter by type
|
|
226
|
+
npx @agent-wiki/mcp-server raw-list # list raw sources
|
|
227
|
+
npx @agent-wiki/mcp-server raw-verify # verify raw file integrity
|
|
228
|
+
npx @agent-wiki/mcp-server lint # run health checks
|
|
236
229
|
```
|
|
237
230
|
|
|
238
231
|
## Design Principles
|
|
@@ -246,6 +239,10 @@ npx agent-wiki lint # run health checks
|
|
|
246
239
|
7. **Code and data separate** — Configurable workspace keeps your knowledge portable and independent.
|
|
247
240
|
8. **Git-native** — Plain Markdown files. Every change is diffable, blameable, and revertable.
|
|
248
241
|
|
|
242
|
+
## Acknowledgments
|
|
243
|
+
|
|
244
|
+
The knowledge compilation architecture is inspired by Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) concept — the idea that LLMs should compile and maintain structured knowledge rather than retrieve raw fragments on every query.
|
|
245
|
+
|
|
249
246
|
## License
|
|
250
247
|
|
|
251
248
|
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@agent-wiki/mcp-server",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.2",
|
|
4
4
|
"description": "Agent-driven knowledge base — immutable raw sources + mutable wiki + self-checking lint. MCP server, no LLM needed.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -17,7 +17,10 @@
|
|
|
17
17
|
"build": "tsc",
|
|
18
18
|
"dev": "tsc --watch",
|
|
19
19
|
"start": "node dist/cli.js",
|
|
20
|
-
"prepare": "npm run build"
|
|
20
|
+
"prepare": "npm run build",
|
|
21
|
+
"release:patch": "gh workflow run release.yml -f bump=patch",
|
|
22
|
+
"release:minor": "gh workflow run release.yml -f bump=minor",
|
|
23
|
+
"release:major": "gh workflow run release.yml -f bump=major"
|
|
21
24
|
},
|
|
22
25
|
"keywords": [
|
|
23
26
|
"mcp",
|