sessionwiki 2.0.0__py3-none-any.whl
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.
- sessionwiki/__init__.py +74 -0
- sessionwiki/__main__.py +6 -0
- sessionwiki/_frontmatter.py +118 -0
- sessionwiki/_system_pages.py +44 -0
- sessionwiki/adapter_config.py +124 -0
- sessionwiki/adapters/__init__.py +134 -0
- sessionwiki/adapters/base.py +191 -0
- sessionwiki/adapters/claude_code.py +77 -0
- sessionwiki/adapters/codex_cli.py +226 -0
- sessionwiki/adapters/contrib/__init__.py +1 -0
- sessionwiki/adapters/contrib/chatgpt.py +252 -0
- sessionwiki/adapters/contrib/copilot_chat.py +121 -0
- sessionwiki/adapters/contrib/copilot_cli.py +115 -0
- sessionwiki/adapters/contrib/cursor.py +100 -0
- sessionwiki/adapters/contrib/gemini_cli.py +74 -0
- sessionwiki/adapters/contrib/obsidian.py +121 -0
- sessionwiki/adapters/opencode.py +169 -0
- sessionwiki/adapters/status.py +58 -0
- sessionwiki/adapters/zcode.py +45 -0
- sessionwiki/audit.py +174 -0
- sessionwiki/backlinks.py +224 -0
- sessionwiki/build.py +2786 -0
- sessionwiki/cache.py +401 -0
- sessionwiki/candidates.py +309 -0
- sessionwiki/categories.py +158 -0
- sessionwiki/changelog_timeline.py +422 -0
- sessionwiki/cli.py +1687 -0
- sessionwiki/compare.py +404 -0
- sessionwiki/completion.py +191 -0
- sessionwiki/confidence.py +179 -0
- sessionwiki/config.py +74 -0
- sessionwiki/config_schedule.py +77 -0
- sessionwiki/context_md.py +182 -0
- sessionwiki/convert.py +1746 -0
- sessionwiki/docs_pages.py +725 -0
- sessionwiki/doctor.py +113 -0
- sessionwiki/exporters.py +680 -0
- sessionwiki/freshness.py +153 -0
- sessionwiki/graph.py +1058 -0
- sessionwiki/graphify_bridge.py +509 -0
- sessionwiki/ingest_queue.py +101 -0
- sessionwiki/lifecycle.py +167 -0
- sessionwiki/link_checker.py +148 -0
- sessionwiki/lint/__init__.py +170 -0
- sessionwiki/lint/rules/__init__.py +69 -0
- sessionwiki/lint/rules/_helpers.py +119 -0
- sessionwiki/lint/rules/claim_verification.py +44 -0
- sessionwiki/lint/rules/content_freshness.py +41 -0
- sessionwiki/lint/rules/contradiction_detection.py +45 -0
- sessionwiki/lint/rules/duplicate_detection.py +164 -0
- sessionwiki/lint/rules/entity_consistency.py +29 -0
- sessionwiki/lint/rules/frontmatter_completeness.py +46 -0
- sessionwiki/lint/rules/frontmatter_count_consistency.py +61 -0
- sessionwiki/lint/rules/frontmatter_validity.py +71 -0
- sessionwiki/lint/rules/index_sync.py +68 -0
- sessionwiki/lint/rules/link_integrity.py +34 -0
- sessionwiki/lint/rules/orphan_detection.py +43 -0
- sessionwiki/lint/rules/stale_candidates.py +59 -0
- sessionwiki/lint/rules/stale_reference_detection.py +42 -0
- sessionwiki/lint/rules/summary_accuracy.py +36 -0
- sessionwiki/lint/rules/tags_topics_convention.py +58 -0
- sessionwiki/lint/rules/tools_consistency.py +65 -0
- sessionwiki/lock.py +126 -0
- sessionwiki/log_reader.py +129 -0
- sessionwiki/manifest.py +132 -0
- sessionwiki/mcp/__init__.py +29 -0
- sessionwiki/mcp/__main__.py +5 -0
- sessionwiki/mcp/server.py +1061 -0
- sessionwiki/models_page.py +291 -0
- sessionwiki/obsidian_output.py +208 -0
- sessionwiki/opencode/__init__.py +1 -0
- sessionwiki/opencode/autosync.py +102 -0
- sessionwiki/opencode/export.py +419 -0
- sessionwiki/opencode/install.py +152 -0
- sessionwiki/pipeline.py +150 -0
- sessionwiki/project_topics.py +213 -0
- sessionwiki/py.typed +0 -0
- sessionwiki/quarantine.py +273 -0
- sessionwiki/queue.py +29 -0
- sessionwiki/references.py +224 -0
- sessionwiki/render/__init__.py +20 -0
- sessionwiki/render/css.py +988 -0
- sessionwiki/render/docs_css.py +463 -0
- sessionwiki/render/js.py +1337 -0
- sessionwiki/schema.py +270 -0
- sessionwiki/search_facets.py +150 -0
- sessionwiki/search_tree.py +184 -0
- sessionwiki/serve.py +91 -0
- sessionwiki/session_export.py +333 -0
- sessionwiki/skill_installer.py +112 -0
- sessionwiki/sync/__init__.py +13 -0
- sessionwiki/sync/status.py +120 -0
- sessionwiki/synth/__init__.py +14 -0
- sessionwiki/synth/agent_delegate.py +327 -0
- sessionwiki/synth/base.py +125 -0
- sessionwiki/synth/cli_helpers.py +98 -0
- sessionwiki/synth/estimate.py +146 -0
- sessionwiki/synth/ollama.py +379 -0
- sessionwiki/synth/openai_compat.py +325 -0
- sessionwiki/synth/pipeline.py +1489 -0
- sessionwiki/tag_utils.py +62 -0
- sessionwiki/tags.py +359 -0
- sessionwiki/vault.py +347 -0
- sessionwiki/viz_heatmap.py +305 -0
- sessionwiki/viz_tokens.py +429 -0
- sessionwiki/viz_tools.py +241 -0
- sessionwiki/watch.py +154 -0
- sessionwiki/zcode/__init__.py +43 -0
- sessionwiki/zcode/autosync.py +150 -0
- sessionwiki/zcode/export.py +568 -0
- sessionwiki/zcode/install.py +386 -0
- sessionwiki-2.0.0.dist-info/METADATA +303 -0
- sessionwiki-2.0.0.dist-info/RECORD +118 -0
- sessionwiki-2.0.0.dist-info/WHEEL +5 -0
- sessionwiki-2.0.0.dist-info/entry_points.txt +2 -0
- sessionwiki-2.0.0.dist-info/licenses/LICENSE +22 -0
- sessionwiki-2.0.0.dist-info/licenses/NOTICE +14 -0
- sessionwiki-2.0.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,1061 @@
|
|
|
1
|
+
"""Full MCP server for sessionwiki (v0.2).
|
|
2
|
+
|
|
3
|
+
Exposes sessionwiki operations as Model Context Protocol tools that any MCP
|
|
4
|
+
client (Claude Desktop, Claude Code, Codex, Cline, Cursor, ChatGPT desktop)
|
|
5
|
+
can call directly via stdio.
|
|
6
|
+
|
|
7
|
+
v0.2 tool surface (6 production tools):
|
|
8
|
+
|
|
9
|
+
- `wiki_query(question)` — search the wiki's index and return relevant
|
|
10
|
+
content from the matching pages
|
|
11
|
+
- `wiki_search(term)` — raw grep over the whole wiki (no synthesis)
|
|
12
|
+
- `wiki_list_sources(project?)` — list raw source files, optionally filtered
|
|
13
|
+
- `wiki_read_page(path)` — return the full content of a single wiki page
|
|
14
|
+
- `wiki_lint()` — run the lint workflow and return the report
|
|
15
|
+
- `wiki_sync(dry_run?)` — trigger a converter sync
|
|
16
|
+
|
|
17
|
+
Protocol: Model Context Protocol, stdio transport, JSON-RPC 2.0.
|
|
18
|
+
Reference: https://modelcontextprotocol.io/
|
|
19
|
+
|
|
20
|
+
Ships as stdlib-only Python — no MCP SDK dependency.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from __future__ import annotations
|
|
24
|
+
|
|
25
|
+
import json
|
|
26
|
+
import re
|
|
27
|
+
import subprocess
|
|
28
|
+
import sys
|
|
29
|
+
import time
|
|
30
|
+
from pathlib import Path
|
|
31
|
+
from typing import Any
|
|
32
|
+
|
|
33
|
+
from sessionwiki import REPO_ROOT, __version__
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
SERVER_INFO = {
|
|
37
|
+
"name": "sessionwiki",
|
|
38
|
+
"version": __version__,
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
PROTOCOL_VERSION = "2024-11-05"
|
|
42
|
+
|
|
43
|
+
# ─── Tool definitions ─────────────────────────────────────────────────────
|
|
44
|
+
|
|
45
|
+
TOOLS = [
|
|
46
|
+
{
|
|
47
|
+
"name": "wiki_query",
|
|
48
|
+
"description": (
|
|
49
|
+
"Search the sessionwiki by keyword and return relevant page content. "
|
|
50
|
+
"Reads wiki/index.md, wiki/overview.md, and any matching pages. "
|
|
51
|
+
"Use for questions like 'what did I decide about X' or 'what's my "
|
|
52
|
+
"preferred approach to Y'."
|
|
53
|
+
),
|
|
54
|
+
"inputSchema": {
|
|
55
|
+
"type": "object",
|
|
56
|
+
"properties": {
|
|
57
|
+
"question": {
|
|
58
|
+
"type": "string",
|
|
59
|
+
"description": "Natural-language question or keyword(s) to search for.",
|
|
60
|
+
},
|
|
61
|
+
"max_pages": {
|
|
62
|
+
"type": "integer",
|
|
63
|
+
"description": "Maximum pages to return (default 5).",
|
|
64
|
+
"default": 5,
|
|
65
|
+
},
|
|
66
|
+
},
|
|
67
|
+
"required": ["question"],
|
|
68
|
+
},
|
|
69
|
+
},
|
|
70
|
+
{
|
|
71
|
+
"name": "wiki_search",
|
|
72
|
+
"description": (
|
|
73
|
+
"Raw grep search across wiki/ and raw/sessions/. No synthesis — "
|
|
74
|
+
"just returns file:line matches. Use when you want the literal "
|
|
75
|
+
"text without LLM interpretation."
|
|
76
|
+
),
|
|
77
|
+
"inputSchema": {
|
|
78
|
+
"type": "object",
|
|
79
|
+
"properties": {
|
|
80
|
+
"term": {
|
|
81
|
+
"type": "string",
|
|
82
|
+
"description": "Search term (literal substring match).",
|
|
83
|
+
},
|
|
84
|
+
"include_raw": {
|
|
85
|
+
"type": "boolean",
|
|
86
|
+
"description": "Also search raw/sessions/ (default false — only wiki/).",
|
|
87
|
+
"default": False,
|
|
88
|
+
},
|
|
89
|
+
},
|
|
90
|
+
"required": ["term"],
|
|
91
|
+
},
|
|
92
|
+
},
|
|
93
|
+
{
|
|
94
|
+
"name": "wiki_list_sources",
|
|
95
|
+
"description": "List all raw source markdown files under raw/sessions/ with their metadata.",
|
|
96
|
+
"inputSchema": {
|
|
97
|
+
"type": "object",
|
|
98
|
+
"properties": {
|
|
99
|
+
"project": {
|
|
100
|
+
"type": "string",
|
|
101
|
+
"description": "Optional project slug to filter by.",
|
|
102
|
+
},
|
|
103
|
+
},
|
|
104
|
+
},
|
|
105
|
+
},
|
|
106
|
+
{
|
|
107
|
+
"name": "wiki_read_page",
|
|
108
|
+
"description": (
|
|
109
|
+
"Return the full content of one wiki or raw page. Path is relative "
|
|
110
|
+
"to the repo root (e.g. 'wiki/sources/clever-munching-parnas.md')."
|
|
111
|
+
),
|
|
112
|
+
"inputSchema": {
|
|
113
|
+
"type": "object",
|
|
114
|
+
"properties": {
|
|
115
|
+
"path": {
|
|
116
|
+
"type": "string",
|
|
117
|
+
"description": "Page path relative to the repo root.",
|
|
118
|
+
},
|
|
119
|
+
},
|
|
120
|
+
"required": ["path"],
|
|
121
|
+
},
|
|
122
|
+
},
|
|
123
|
+
{
|
|
124
|
+
"name": "wiki_lint",
|
|
125
|
+
"description": (
|
|
126
|
+
"Run the lint workflow over the wiki: find orphan pages, broken "
|
|
127
|
+
"wikilinks, contradictions, and stale summaries. Returns a JSON "
|
|
128
|
+
"report."
|
|
129
|
+
),
|
|
130
|
+
"inputSchema": {
|
|
131
|
+
"type": "object",
|
|
132
|
+
"properties": {},
|
|
133
|
+
},
|
|
134
|
+
},
|
|
135
|
+
{
|
|
136
|
+
"name": "wiki_sync",
|
|
137
|
+
"description": (
|
|
138
|
+
"Run the session-transcript converter to pull in any new sessions "
|
|
139
|
+
"from the agent's session store into raw/sessions/. Returns the "
|
|
140
|
+
"converter's summary line. Defaults to dry-run; pass confirm=true "
|
|
141
|
+
"to actually write."
|
|
142
|
+
),
|
|
143
|
+
"inputSchema": {
|
|
144
|
+
"type": "object",
|
|
145
|
+
"properties": {
|
|
146
|
+
# #sec-12 (#556): default to dry_run=true so an MCP client
|
|
147
|
+
# can't silently mutate raw/ on a misclick / hallucinated
|
|
148
|
+
# tool call. Pass `confirm: true` to actually write.
|
|
149
|
+
"dry_run": {
|
|
150
|
+
"type": "boolean",
|
|
151
|
+
"description": (
|
|
152
|
+
"If true (default), preview without writing. Set "
|
|
153
|
+
"false ONLY together with confirm=true."
|
|
154
|
+
),
|
|
155
|
+
"default": True,
|
|
156
|
+
},
|
|
157
|
+
"confirm": {
|
|
158
|
+
"type": "boolean",
|
|
159
|
+
"description": (
|
|
160
|
+
"Required to actually write. Without confirm=true "
|
|
161
|
+
"the call always runs as a dry-run regardless of "
|
|
162
|
+
"dry_run."
|
|
163
|
+
),
|
|
164
|
+
"default": False,
|
|
165
|
+
},
|
|
166
|
+
},
|
|
167
|
+
},
|
|
168
|
+
},
|
|
169
|
+
{
|
|
170
|
+
"name": "wiki_export",
|
|
171
|
+
"description": (
|
|
172
|
+
"Dump the entire wiki in a machine-readable format for AI agents. "
|
|
173
|
+
"Returns the requested format as text. Use 'llms-txt' for the "
|
|
174
|
+
"short llms.txt index, 'llms-full-txt' for the flattened content "
|
|
175
|
+
"dump, 'jsonld' for the schema.org JSON-LD graph, 'sitemap' for "
|
|
176
|
+
"the sitemap.xml, or 'list' to list every available export."
|
|
177
|
+
),
|
|
178
|
+
"inputSchema": {
|
|
179
|
+
"type": "object",
|
|
180
|
+
"properties": {
|
|
181
|
+
"format": {
|
|
182
|
+
"type": "string",
|
|
183
|
+
"enum": ["llms-txt", "llms-full-txt", "jsonld", "sitemap", "rss", "manifest", "list"],
|
|
184
|
+
"description": "Which export format to return.",
|
|
185
|
+
},
|
|
186
|
+
},
|
|
187
|
+
"required": ["format"],
|
|
188
|
+
},
|
|
189
|
+
},
|
|
190
|
+
# v1.0 (#159) — 5 new MCP tools for confidence, lifecycle, dashboard,
|
|
191
|
+
# entity search, and category browse.
|
|
192
|
+
{
|
|
193
|
+
"name": "wiki_confidence",
|
|
194
|
+
"description": (
|
|
195
|
+
"Return confidence scores for wiki pages. Filters by minimum "
|
|
196
|
+
"confidence threshold. Pages below threshold may need review."
|
|
197
|
+
),
|
|
198
|
+
"inputSchema": {
|
|
199
|
+
"type": "object",
|
|
200
|
+
"properties": {
|
|
201
|
+
"min_confidence": {
|
|
202
|
+
"type": "number",
|
|
203
|
+
"description": "Only return pages with confidence >= this (0.0-1.0). Default 0.",
|
|
204
|
+
"default": 0.0,
|
|
205
|
+
},
|
|
206
|
+
"max_confidence": {
|
|
207
|
+
"type": "number",
|
|
208
|
+
"description": "Only return pages with confidence <= this (0.0-1.0). Default 1.0.",
|
|
209
|
+
"default": 1.0,
|
|
210
|
+
},
|
|
211
|
+
},
|
|
212
|
+
},
|
|
213
|
+
},
|
|
214
|
+
{
|
|
215
|
+
"name": "wiki_lifecycle",
|
|
216
|
+
"description": (
|
|
217
|
+
"List pages by lifecycle state: draft, reviewed, verified, stale, "
|
|
218
|
+
"or archived. Use to find pages needing review or archival."
|
|
219
|
+
),
|
|
220
|
+
"inputSchema": {
|
|
221
|
+
"type": "object",
|
|
222
|
+
"properties": {
|
|
223
|
+
"state": {
|
|
224
|
+
"type": "string",
|
|
225
|
+
"enum": ["draft", "reviewed", "verified", "stale", "archived"],
|
|
226
|
+
"description": "Which lifecycle state to filter by.",
|
|
227
|
+
},
|
|
228
|
+
},
|
|
229
|
+
"required": ["state"],
|
|
230
|
+
},
|
|
231
|
+
},
|
|
232
|
+
{
|
|
233
|
+
"name": "wiki_dashboard",
|
|
234
|
+
"description": (
|
|
235
|
+
"Return a summary of wiki health: page counts by type, "
|
|
236
|
+
"confidence distribution, lifecycle distribution, stale pages, "
|
|
237
|
+
"and recent updates."
|
|
238
|
+
),
|
|
239
|
+
"inputSchema": {
|
|
240
|
+
"type": "object",
|
|
241
|
+
"properties": {},
|
|
242
|
+
},
|
|
243
|
+
},
|
|
244
|
+
{
|
|
245
|
+
"name": "wiki_entity_search",
|
|
246
|
+
"description": (
|
|
247
|
+
"Search entities by name or entity_type. Returns matching "
|
|
248
|
+
"entity pages with their metadata."
|
|
249
|
+
),
|
|
250
|
+
"inputSchema": {
|
|
251
|
+
"type": "object",
|
|
252
|
+
"properties": {
|
|
253
|
+
"name": {
|
|
254
|
+
"type": "string",
|
|
255
|
+
"description": "Entity name substring (case-insensitive).",
|
|
256
|
+
},
|
|
257
|
+
"entity_type": {
|
|
258
|
+
"type": "string",
|
|
259
|
+
"enum": ["person", "org", "tool", "concept", "api", "library", "project"],
|
|
260
|
+
"description": "Filter by entity type.",
|
|
261
|
+
},
|
|
262
|
+
},
|
|
263
|
+
},
|
|
264
|
+
},
|
|
265
|
+
{
|
|
266
|
+
"name": "wiki_category_browse",
|
|
267
|
+
"description": (
|
|
268
|
+
"List tags and the count of pages for each. Optionally return "
|
|
269
|
+
"all pages for a specific tag."
|
|
270
|
+
),
|
|
271
|
+
"inputSchema": {
|
|
272
|
+
"type": "object",
|
|
273
|
+
"properties": {
|
|
274
|
+
"tag": {
|
|
275
|
+
"type": "string",
|
|
276
|
+
"description": "Optional tag to drill into. If omitted, returns counts for all tags.",
|
|
277
|
+
},
|
|
278
|
+
"min_count": {
|
|
279
|
+
"type": "integer",
|
|
280
|
+
"description": "Only include tags with >= this many pages (default 1).",
|
|
281
|
+
"default": 1,
|
|
282
|
+
},
|
|
283
|
+
},
|
|
284
|
+
},
|
|
285
|
+
},
|
|
286
|
+
]
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
# ─── Tool implementations ─────────────────────────────────────────────────
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
# #482: top-level directories the MCP read-page tool is allowed to
|
|
293
|
+
# return content from. Anything outside this set is rejected even
|
|
294
|
+
# though it lives under REPO_ROOT — e.g. .git/, .env, .venv/, the
|
|
295
|
+
# state files (.llmwiki-state.json contains absolute paths to every
|
|
296
|
+
# Claude session file → host directory listing leak), and dotfiles
|
|
297
|
+
# in general. README, CHANGELOG, CONTRIBUTING are allowed by name
|
|
298
|
+
# because they're the documentation surface every consumer expects.
|
|
299
|
+
_READ_PAGE_ALLOWED_DIRS: tuple[str, ...] = (
|
|
300
|
+
"wiki", "raw", "docs", "examples", "site",
|
|
301
|
+
)
|
|
302
|
+
_READ_PAGE_ALLOWED_ROOT_FILES: frozenset[str] = frozenset({
|
|
303
|
+
"README.md", "CHANGELOG.md", "CONTRIBUTING.md",
|
|
304
|
+
"LICENSE", "LICENSE.md",
|
|
305
|
+
})
|
|
306
|
+
|
|
307
|
+
|
|
308
|
+
def _safe_path(rel: str) -> Path | None:
|
|
309
|
+
"""Resolve a user-supplied path relative to REPO_ROOT and refuse if it
|
|
310
|
+
escapes the repo (path traversal guard)."""
|
|
311
|
+
if not rel:
|
|
312
|
+
return None
|
|
313
|
+
p = (REPO_ROOT / rel).resolve()
|
|
314
|
+
try:
|
|
315
|
+
p.relative_to(REPO_ROOT.resolve())
|
|
316
|
+
except ValueError:
|
|
317
|
+
return None
|
|
318
|
+
return p
|
|
319
|
+
|
|
320
|
+
|
|
321
|
+
def _is_read_page_allowed(p: Path) -> bool:
|
|
322
|
+
"""#482: restrict `tool_wiki_read_page` to a documented surface.
|
|
323
|
+
|
|
324
|
+
The path-traversal guard in `_safe_path` only checks the file is
|
|
325
|
+
*under* REPO_ROOT. That still leaks every dotfile, the .git
|
|
326
|
+
directory, the state files, and node_modules. Apply an explicit
|
|
327
|
+
allowlist on top — the docs surface, plus the user's wiki/raw
|
|
328
|
+
content. Anything else is silently a "not found".
|
|
329
|
+
"""
|
|
330
|
+
try:
|
|
331
|
+
rel_parts = p.resolve().relative_to(REPO_ROOT.resolve()).parts
|
|
332
|
+
except ValueError:
|
|
333
|
+
return False
|
|
334
|
+
if not rel_parts:
|
|
335
|
+
return False
|
|
336
|
+
head = rel_parts[0]
|
|
337
|
+
# Top-level allowlisted directory?
|
|
338
|
+
if head in _READ_PAGE_ALLOWED_DIRS:
|
|
339
|
+
return True
|
|
340
|
+
# Single allowlisted file at the root?
|
|
341
|
+
if len(rel_parts) == 1 and head in _READ_PAGE_ALLOWED_ROOT_FILES:
|
|
342
|
+
return True
|
|
343
|
+
return False
|
|
344
|
+
|
|
345
|
+
|
|
346
|
+
def tool_wiki_query(args: dict[str, Any]) -> dict[str, Any]:
|
|
347
|
+
question = (args.get("question") or "").strip()
|
|
348
|
+
max_pages = int(args.get("max_pages", 5))
|
|
349
|
+
if not question:
|
|
350
|
+
return _err("question is required")
|
|
351
|
+
|
|
352
|
+
wiki = REPO_ROOT / "wiki"
|
|
353
|
+
if not wiki.exists():
|
|
354
|
+
return _ok(
|
|
355
|
+
"wiki/ does not exist yet — run `sessionwiki init` and `/wiki-sync` first"
|
|
356
|
+
)
|
|
357
|
+
|
|
358
|
+
# Read the index + overview
|
|
359
|
+
index = (wiki / "index.md").read_text(encoding="utf-8") if (wiki / "index.md").exists() else ""
|
|
360
|
+
overview = (wiki / "overview.md").read_text(encoding="utf-8") if (wiki / "overview.md").exists() else ""
|
|
361
|
+
|
|
362
|
+
# Scan every .md under wiki/ for matches on title + body.
|
|
363
|
+
# #418: ranking is now length-normalised — body matches are
|
|
364
|
+
# divided by ``log2(max(len(content), 256))`` so a 1MB log
|
|
365
|
+
# page can't beat a perfectly-relevant 1-paragraph entity page
|
|
366
|
+
# just by accidentally containing every query token. Title
|
|
367
|
+
# matches are unchanged since titles are already short and
|
|
368
|
+
# high-signal.
|
|
369
|
+
query_lower = question.lower()
|
|
370
|
+
tokens = [t for t in re.split(r"\W+", query_lower) if t]
|
|
371
|
+
matches: list[tuple[float, Path, str]] = []
|
|
372
|
+
# #483: bound input bytes so a single large file or a giant corpus
|
|
373
|
+
# can't OOM the MCP server.
|
|
374
|
+
budget = _MCP_SCAN_AGGREGATE_BYTES
|
|
375
|
+
skipped_oversize = 0
|
|
376
|
+
for page in wiki.rglob("*.md"):
|
|
377
|
+
if budget <= 0:
|
|
378
|
+
break
|
|
379
|
+
content, consumed = _read_capped(page, remaining_budget=budget)
|
|
380
|
+
if consumed == 0:
|
|
381
|
+
try:
|
|
382
|
+
if page.stat().st_size > _MCP_SCAN_PER_FILE_BYTES:
|
|
383
|
+
skipped_oversize += 1
|
|
384
|
+
except OSError:
|
|
385
|
+
pass
|
|
386
|
+
continue
|
|
387
|
+
budget -= consumed
|
|
388
|
+
content_lower = content.lower()
|
|
389
|
+
body_score = 0
|
|
390
|
+
if query_lower in content_lower:
|
|
391
|
+
body_score += 50
|
|
392
|
+
body_score += sum(10 for t in tokens if t in content_lower)
|
|
393
|
+
# Length normalisation: divide raw body score by
|
|
394
|
+
# log2(max(len, 256)). The 256-byte floor keeps very short
|
|
395
|
+
# pages (frontmatter-only) from getting a massive boost on
|
|
396
|
+
# zero-token queries.
|
|
397
|
+
if body_score > 0:
|
|
398
|
+
import math as _math
|
|
399
|
+
length_factor = _math.log2(max(len(content), 256))
|
|
400
|
+
normalised_body = body_score / length_factor
|
|
401
|
+
else:
|
|
402
|
+
normalised_body = 0.0
|
|
403
|
+
# Title bonus — unchanged. Titles are already short and
|
|
404
|
+
# high-signal; no normalisation needed.
|
|
405
|
+
title_score = 0
|
|
406
|
+
title_match = re.search(r'^title:\s*"?([^"\n]+)', content, re.MULTILINE)
|
|
407
|
+
if title_match:
|
|
408
|
+
title = title_match.group(1).lower()
|
|
409
|
+
if query_lower in title:
|
|
410
|
+
title_score += 100
|
|
411
|
+
title_score += sum(20 for t in tokens if t in title)
|
|
412
|
+
score = normalised_body + title_score
|
|
413
|
+
if score > 0:
|
|
414
|
+
snippet = _extract_snippet(content, tokens, max_chars=400)
|
|
415
|
+
matches.append((score, page, snippet))
|
|
416
|
+
|
|
417
|
+
matches.sort(key=lambda x: -x[0])
|
|
418
|
+
top = matches[:max_pages]
|
|
419
|
+
|
|
420
|
+
out = [f"# Query: {question}\n"]
|
|
421
|
+
if not top:
|
|
422
|
+
out.append("No matching pages found.\n")
|
|
423
|
+
out.append("\n## wiki/index.md\n\n" + index[:1500])
|
|
424
|
+
else:
|
|
425
|
+
for score, page, snippet in top:
|
|
426
|
+
rel = page.relative_to(REPO_ROOT)
|
|
427
|
+
out.append(f"## `{rel}` (score: {score:.1f})\n")
|
|
428
|
+
out.append(snippet)
|
|
429
|
+
out.append("")
|
|
430
|
+
out.append("---\n")
|
|
431
|
+
out.append("## Overview context\n")
|
|
432
|
+
out.append(overview[:1000] if overview else "(no overview.md)")
|
|
433
|
+
|
|
434
|
+
return _ok("\n".join(out))
|
|
435
|
+
|
|
436
|
+
|
|
437
|
+
def _extract_snippet(content: str, tokens: list[str], max_chars: int = 400) -> str:
|
|
438
|
+
"""Return a ±max_chars window around the first token match, or the first
|
|
439
|
+
max_chars of the body if no match."""
|
|
440
|
+
content_lower = content.lower()
|
|
441
|
+
for t in tokens:
|
|
442
|
+
idx = content_lower.find(t)
|
|
443
|
+
if idx >= 0:
|
|
444
|
+
start = max(0, idx - max_chars // 2)
|
|
445
|
+
end = min(len(content), idx + max_chars // 2)
|
|
446
|
+
prefix = "…" if start > 0 else ""
|
|
447
|
+
suffix = "…" if end < len(content) else ""
|
|
448
|
+
return prefix + content[start:end] + suffix
|
|
449
|
+
return content[:max_chars] + ("…" if len(content) > max_chars else "")
|
|
450
|
+
|
|
451
|
+
|
|
452
|
+
_SEARCH_HIT_CAP = 200
|
|
453
|
+
|
|
454
|
+
# #483: per-file + aggregate byte caps for wiki_search / wiki_query.
|
|
455
|
+
# Without these, a single large file (e.g. a 100MB Obsidian transcript
|
|
456
|
+
# with embedded video, or a malicious user-supplied .md) gets fully
|
|
457
|
+
# read into memory by every MCP call. _SEARCH_HIT_CAP capped output
|
|
458
|
+
# only — the loop still read every byte of every file. Cap inputs
|
|
459
|
+
# explicitly so the worst-case is bounded regardless of corpus shape.
|
|
460
|
+
_MCP_SCAN_PER_FILE_BYTES = 4 * 1024 * 1024 # 4 MiB / file
|
|
461
|
+
_MCP_SCAN_AGGREGATE_BYTES = 50 * 1024 * 1024 # 50 MiB / call
|
|
462
|
+
|
|
463
|
+
|
|
464
|
+
def _read_capped(p: Path, *, remaining_budget: int) -> tuple[str, int]:
|
|
465
|
+
"""Read up to min(per-file cap, remaining_budget) bytes of `p`.
|
|
466
|
+
|
|
467
|
+
Returns (text, bytes_consumed). ``bytes_consumed == 0`` signals
|
|
468
|
+
the file was skipped entirely (over-budget or unreadable). Caller
|
|
469
|
+
decrements the aggregate budget by ``bytes_consumed`` and bails
|
|
470
|
+
when it hits zero.
|
|
471
|
+
"""
|
|
472
|
+
try:
|
|
473
|
+
size = p.stat().st_size
|
|
474
|
+
except OSError:
|
|
475
|
+
return "", 0
|
|
476
|
+
cap = min(_MCP_SCAN_PER_FILE_BYTES, max(0, remaining_budget))
|
|
477
|
+
if size > _MCP_SCAN_PER_FILE_BYTES:
|
|
478
|
+
# Skip the file entirely — do not partial-read. The truncation
|
|
479
|
+
# would slice query tokens across the boundary and produce
|
|
480
|
+
# confusing partial hits.
|
|
481
|
+
return "", 0
|
|
482
|
+
if cap <= 0:
|
|
483
|
+
return "", 0
|
|
484
|
+
try:
|
|
485
|
+
with p.open("rb") as f:
|
|
486
|
+
raw = f.read(cap + 1)
|
|
487
|
+
except OSError:
|
|
488
|
+
return "", 0
|
|
489
|
+
# If we read more than cap, the file grew between stat and read.
|
|
490
|
+
# Trust the stat-based skip above; truncate defensively here.
|
|
491
|
+
if len(raw) > cap:
|
|
492
|
+
return "", 0
|
|
493
|
+
try:
|
|
494
|
+
return raw.decode("utf-8", errors="replace"), len(raw)
|
|
495
|
+
except Exception:
|
|
496
|
+
return "", 0
|
|
497
|
+
|
|
498
|
+
|
|
499
|
+
def tool_wiki_search(args: dict[str, Any]) -> dict[str, Any]:
|
|
500
|
+
# #413: the old loop had three nested terminators (`for line`,
|
|
501
|
+
# `for p`, `for root`) but only the inner two had a 200-cap break.
|
|
502
|
+
# With include_raw=True the cap was effectively per-root, so we
|
|
503
|
+
# could return up to 400 hits when the schema implies 200, while
|
|
504
|
+
# still scanning the entire raw/ tree after the wiki/ tree had
|
|
505
|
+
# already capped. Restructured as a single iterator with one
|
|
506
|
+
# termination check, and the search term is lowercased once.
|
|
507
|
+
term = (args.get("term") or "").strip()
|
|
508
|
+
include_raw = bool(args.get("include_raw", False))
|
|
509
|
+
if not term:
|
|
510
|
+
return _err("term is required")
|
|
511
|
+
|
|
512
|
+
roots = [REPO_ROOT / "wiki"]
|
|
513
|
+
if include_raw:
|
|
514
|
+
roots.append(REPO_ROOT / "raw" / "sessions")
|
|
515
|
+
|
|
516
|
+
term_lower = term.lower()
|
|
517
|
+
hits: list[dict[str, Any]] = []
|
|
518
|
+
truncated = False
|
|
519
|
+
# #483: aggregate byte budget across all roots, plus per-file cap
|
|
520
|
+
# via _read_capped. Output cap (_SEARCH_HIT_CAP) is unchanged.
|
|
521
|
+
budget = _MCP_SCAN_AGGREGATE_BYTES
|
|
522
|
+
skipped_oversize = 0
|
|
523
|
+
for root in roots:
|
|
524
|
+
if truncated or budget <= 0:
|
|
525
|
+
break
|
|
526
|
+
if not root.exists():
|
|
527
|
+
continue
|
|
528
|
+
for p in root.rglob("*.md"):
|
|
529
|
+
if truncated or budget <= 0:
|
|
530
|
+
break
|
|
531
|
+
text, consumed = _read_capped(p, remaining_budget=budget)
|
|
532
|
+
if consumed == 0:
|
|
533
|
+
try:
|
|
534
|
+
if p.stat().st_size > _MCP_SCAN_PER_FILE_BYTES:
|
|
535
|
+
skipped_oversize += 1
|
|
536
|
+
except OSError:
|
|
537
|
+
pass
|
|
538
|
+
continue
|
|
539
|
+
budget -= consumed
|
|
540
|
+
for i, line in enumerate(text.splitlines(), start=1):
|
|
541
|
+
if term_lower in line.lower():
|
|
542
|
+
hits.append(
|
|
543
|
+
{
|
|
544
|
+
"path": str(p.relative_to(REPO_ROOT)),
|
|
545
|
+
"line": i,
|
|
546
|
+
"text": line.strip()[:200],
|
|
547
|
+
}
|
|
548
|
+
)
|
|
549
|
+
if len(hits) >= _SEARCH_HIT_CAP:
|
|
550
|
+
truncated = True
|
|
551
|
+
break
|
|
552
|
+
# #483: surface skipped-oversize count so callers know we didn't
|
|
553
|
+
# silently miss content from huge files.
|
|
554
|
+
return _ok(json.dumps({
|
|
555
|
+
"term": term,
|
|
556
|
+
"matches": hits,
|
|
557
|
+
"truncated": truncated,
|
|
558
|
+
"skipped_oversize_files": skipped_oversize,
|
|
559
|
+
}, indent=2))
|
|
560
|
+
|
|
561
|
+
|
|
562
|
+
def tool_wiki_list_sources(args: dict[str, Any]) -> dict[str, Any]:
|
|
563
|
+
project_filter = args.get("project")
|
|
564
|
+
raw_sessions = REPO_ROOT / "raw" / "sessions"
|
|
565
|
+
if not raw_sessions.exists():
|
|
566
|
+
return _ok(json.dumps([], indent=2))
|
|
567
|
+
out = []
|
|
568
|
+
for p in sorted(raw_sessions.rglob("*.md")):
|
|
569
|
+
project = p.parent.name
|
|
570
|
+
if project_filter and project_filter not in project:
|
|
571
|
+
continue
|
|
572
|
+
try:
|
|
573
|
+
size = p.stat().st_size
|
|
574
|
+
except OSError:
|
|
575
|
+
continue
|
|
576
|
+
out.append(
|
|
577
|
+
{
|
|
578
|
+
"path": str(p.relative_to(REPO_ROOT)),
|
|
579
|
+
"project": project,
|
|
580
|
+
"filename": p.name,
|
|
581
|
+
"size_bytes": size,
|
|
582
|
+
}
|
|
583
|
+
)
|
|
584
|
+
return _ok(json.dumps(out, indent=2))
|
|
585
|
+
|
|
586
|
+
|
|
587
|
+
def tool_wiki_read_page(args: dict[str, Any]) -> dict[str, Any]:
|
|
588
|
+
rel = args.get("path")
|
|
589
|
+
if not rel:
|
|
590
|
+
return _err("path is required")
|
|
591
|
+
p = _safe_path(rel)
|
|
592
|
+
if p is None:
|
|
593
|
+
return _err(f"path escapes repo root: {rel!r}")
|
|
594
|
+
# #482: restrict to documented allowlist (wiki/, raw/, docs/,
|
|
595
|
+
# examples/, site/, plus README/CHANGELOG/etc. at the root).
|
|
596
|
+
# Reject .git/, .env, .llmwiki-state.json, node_modules, etc.
|
|
597
|
+
# even though they live under REPO_ROOT.
|
|
598
|
+
if not _is_read_page_allowed(p):
|
|
599
|
+
return _err(
|
|
600
|
+
f"path is outside the readable surface: {rel!r}. "
|
|
601
|
+
f"Allowed: {', '.join(_READ_PAGE_ALLOWED_DIRS)}/, "
|
|
602
|
+
f"plus {', '.join(sorted(_READ_PAGE_ALLOWED_ROOT_FILES))} at the root."
|
|
603
|
+
)
|
|
604
|
+
if not p.exists():
|
|
605
|
+
return _err(f"path does not exist: {rel}")
|
|
606
|
+
if not p.is_file():
|
|
607
|
+
return _err(f"path is not a file: {rel}")
|
|
608
|
+
try:
|
|
609
|
+
content = p.read_text(encoding="utf-8")
|
|
610
|
+
except OSError as e:
|
|
611
|
+
return _err(f"read error: {e}")
|
|
612
|
+
return _ok(content)
|
|
613
|
+
|
|
614
|
+
|
|
615
|
+
def tool_wiki_lint(args: dict[str, Any]) -> dict[str, Any]:
|
|
616
|
+
"""Run a basic lint pass over wiki/ and return a JSON report.
|
|
617
|
+
|
|
618
|
+
This is the programmatic equivalent of the /wiki-lint slash command — but
|
|
619
|
+
without any LLM synthesis. It just walks the files and reports structural
|
|
620
|
+
issues.
|
|
621
|
+
"""
|
|
622
|
+
wiki = REPO_ROOT / "wiki"
|
|
623
|
+
if not wiki.exists():
|
|
624
|
+
return _err("wiki/ does not exist")
|
|
625
|
+
|
|
626
|
+
# 1. Collect all pages and their slugs
|
|
627
|
+
pages: dict[str, Path] = {}
|
|
628
|
+
for p in wiki.rglob("*.md"):
|
|
629
|
+
slug = p.stem
|
|
630
|
+
pages[slug] = p
|
|
631
|
+
|
|
632
|
+
# 2. Collect all wikilinks
|
|
633
|
+
wikilink_re = re.compile(r"\[\[([^\]|]+)(?:\|[^\]]*)?\]\]")
|
|
634
|
+
out_links: dict[str, set[str]] = {}
|
|
635
|
+
all_links: set[str] = set()
|
|
636
|
+
for slug, path in pages.items():
|
|
637
|
+
try:
|
|
638
|
+
text = path.read_text(encoding="utf-8")
|
|
639
|
+
except OSError:
|
|
640
|
+
continue
|
|
641
|
+
links = set(wikilink_re.findall(text))
|
|
642
|
+
out_links[slug] = links
|
|
643
|
+
all_links.update(links)
|
|
644
|
+
|
|
645
|
+
# 3. Compute in-degree
|
|
646
|
+
in_deg: dict[str, int] = {slug: 0 for slug in pages}
|
|
647
|
+
for slug, links in out_links.items():
|
|
648
|
+
for target in links:
|
|
649
|
+
if target in in_deg:
|
|
650
|
+
in_deg[target] += 1
|
|
651
|
+
|
|
652
|
+
orphans = [slug for slug, d in in_deg.items() if d == 0 and slug not in ("index", "overview", "log")]
|
|
653
|
+
broken_links: list[dict[str, str]] = []
|
|
654
|
+
for slug, links in out_links.items():
|
|
655
|
+
for target in links:
|
|
656
|
+
if target not in pages:
|
|
657
|
+
broken_links.append({"page": slug, "broken_link": target})
|
|
658
|
+
|
|
659
|
+
report = {
|
|
660
|
+
"total_pages": len(pages),
|
|
661
|
+
"orphans": orphans[:50],
|
|
662
|
+
"orphan_count": len(orphans),
|
|
663
|
+
"broken_links": broken_links[:50],
|
|
664
|
+
"broken_link_count": len(broken_links),
|
|
665
|
+
}
|
|
666
|
+
return _ok(json.dumps(report, indent=2))
|
|
667
|
+
|
|
668
|
+
|
|
669
|
+
def tool_wiki_sync(args: dict[str, Any]) -> dict[str, Any]:
|
|
670
|
+
# #sec-12 (#556): default to dry_run=true. Real writes require BOTH
|
|
671
|
+
# dry_run=false AND confirm=true. Either flag missing = dry-run.
|
|
672
|
+
dry_run = bool(args.get("dry_run", True))
|
|
673
|
+
confirm = bool(args.get("confirm", False))
|
|
674
|
+
if not dry_run and not confirm:
|
|
675
|
+
# Caller asked for live sync without confirmation — downgrade to
|
|
676
|
+
# dry-run + tell them why. Better than silently mutating raw/.
|
|
677
|
+
dry_run = True
|
|
678
|
+
cmd = [sys.executable, "-m", "sessionwiki", "sync"]
|
|
679
|
+
if dry_run:
|
|
680
|
+
cmd.append("--dry-run")
|
|
681
|
+
# #py-h1 (#582): capture_output=True buffers all stdout in RAM. A
|
|
682
|
+
# very chatty sync (thousands of sessions) can blow past the
|
|
683
|
+
# 1 GB-ish ceiling Python can hold + grow before OOM-killing.
|
|
684
|
+
# Stream stdout via Popen + readline, capping the captured tail
|
|
685
|
+
# to a fixed byte budget so the MCP response stays bounded.
|
|
686
|
+
OUTPUT_CAP_BYTES = 256 * 1024 # 256 KB tail in the response
|
|
687
|
+
captured: list[str] = []
|
|
688
|
+
captured_bytes = 0
|
|
689
|
+
truncated = False
|
|
690
|
+
try:
|
|
691
|
+
proc = subprocess.Popen(
|
|
692
|
+
cmd,
|
|
693
|
+
stdout=subprocess.PIPE,
|
|
694
|
+
stderr=subprocess.STDOUT,
|
|
695
|
+
text=True,
|
|
696
|
+
cwd=str(REPO_ROOT),
|
|
697
|
+
)
|
|
698
|
+
# Read line-by-line so a hung child doesn't block forever — the
|
|
699
|
+
# outer try wraps a 120s timeout via proc.wait below.
|
|
700
|
+
assert proc.stdout is not None
|
|
701
|
+
deadline = time.time() + 120.0
|
|
702
|
+
for line in proc.stdout:
|
|
703
|
+
if captured_bytes < OUTPUT_CAP_BYTES:
|
|
704
|
+
captured.append(line)
|
|
705
|
+
captured_bytes += len(line)
|
|
706
|
+
else:
|
|
707
|
+
truncated = True
|
|
708
|
+
if time.time() > deadline:
|
|
709
|
+
proc.kill()
|
|
710
|
+
return _err("sync timed out after 120s")
|
|
711
|
+
proc.wait(timeout=max(0.1, deadline - time.time()))
|
|
712
|
+
except subprocess.TimeoutExpired:
|
|
713
|
+
try: proc.kill() # type: ignore[name-defined]
|
|
714
|
+
except Exception: pass
|
|
715
|
+
return _err("sync timed out after 120s")
|
|
716
|
+
except (OSError, subprocess.SubprocessError) as e:
|
|
717
|
+
return _err(f"sync failed: {e}")
|
|
718
|
+
output = "".join(captured)
|
|
719
|
+
if truncated:
|
|
720
|
+
output += f"\n[output truncated at {OUTPUT_CAP_BYTES // 1024} KB]"
|
|
721
|
+
return _ok(output or "(no output)")
|
|
722
|
+
|
|
723
|
+
|
|
724
|
+
def tool_wiki_export(args: dict[str, Any]) -> dict[str, Any]:
|
|
725
|
+
"""Return one of the AI-consumable export files (v0.4)."""
|
|
726
|
+
fmt = args.get("format")
|
|
727
|
+
site_dir = REPO_ROOT / "site"
|
|
728
|
+
|
|
729
|
+
if fmt == "list":
|
|
730
|
+
candidates = [
|
|
731
|
+
"llms.txt",
|
|
732
|
+
"llms-full.txt",
|
|
733
|
+
"graph.jsonld",
|
|
734
|
+
"sitemap.xml",
|
|
735
|
+
"rss.xml",
|
|
736
|
+
"robots.txt",
|
|
737
|
+
"ai-readme.md",
|
|
738
|
+
"manifest.json",
|
|
739
|
+
"search-index.json",
|
|
740
|
+
]
|
|
741
|
+
out = []
|
|
742
|
+
for name in candidates:
|
|
743
|
+
p = site_dir / name
|
|
744
|
+
if p.exists():
|
|
745
|
+
out.append({"format": name, "size_bytes": p.stat().st_size, "url": name})
|
|
746
|
+
return _ok(json.dumps(out, indent=2))
|
|
747
|
+
|
|
748
|
+
mapping = {
|
|
749
|
+
"llms-txt": "llms.txt",
|
|
750
|
+
"llms-full-txt": "llms-full.txt",
|
|
751
|
+
"jsonld": "graph.jsonld",
|
|
752
|
+
"sitemap": "sitemap.xml",
|
|
753
|
+
"rss": "rss.xml",
|
|
754
|
+
"manifest": "manifest.json",
|
|
755
|
+
}
|
|
756
|
+
filename = mapping.get(fmt)
|
|
757
|
+
if not filename:
|
|
758
|
+
return _err(f"unknown format: {fmt}. Valid: {sorted(mapping.keys())} + 'list'")
|
|
759
|
+
p = site_dir / filename
|
|
760
|
+
if not p.exists():
|
|
761
|
+
return _err(f"{filename} does not exist. Run 'sessionwiki build' first.")
|
|
762
|
+
try:
|
|
763
|
+
content = p.read_text(encoding="utf-8")
|
|
764
|
+
except OSError as e:
|
|
765
|
+
return _err(f"read error: {e}")
|
|
766
|
+
# Cap response size at 200 KB to keep MCP responses sane
|
|
767
|
+
if len(content) > 200 * 1024:
|
|
768
|
+
content = content[: 200 * 1024] + f"\n\n…(truncated at 200 KB; full file is {p.stat().st_size} bytes at /{filename})"
|
|
769
|
+
return _ok(content)
|
|
770
|
+
|
|
771
|
+
|
|
772
|
+
def _ok(text: str) -> dict[str, Any]:
|
|
773
|
+
return {"content": [{"type": "text", "text": text}], "isError": False}
|
|
774
|
+
|
|
775
|
+
|
|
776
|
+
def _err(text: str) -> dict[str, Any]:
|
|
777
|
+
return {"content": [{"type": "text", "text": text}], "isError": True}
|
|
778
|
+
|
|
779
|
+
|
|
780
|
+
def tool_wiki_confidence(args: dict[str, Any]) -> dict[str, Any]:
|
|
781
|
+
"""List pages filtered by confidence score range (v1.0 · #159)."""
|
|
782
|
+
from sessionwiki.lint import load_pages
|
|
783
|
+
|
|
784
|
+
min_c = float(args.get("min_confidence", 0.0))
|
|
785
|
+
max_c = float(args.get("max_confidence", 1.0))
|
|
786
|
+
|
|
787
|
+
wiki = REPO_ROOT / "wiki"
|
|
788
|
+
pages = load_pages(wiki)
|
|
789
|
+
|
|
790
|
+
results: list[dict[str, Any]] = []
|
|
791
|
+
for rel, page in pages.items():
|
|
792
|
+
conf_raw = page["meta"].get("confidence", "")
|
|
793
|
+
if not conf_raw:
|
|
794
|
+
continue
|
|
795
|
+
try:
|
|
796
|
+
conf = float(conf_raw)
|
|
797
|
+
except (ValueError, TypeError):
|
|
798
|
+
continue
|
|
799
|
+
if min_c <= conf <= max_c:
|
|
800
|
+
results.append({
|
|
801
|
+
"path": rel,
|
|
802
|
+
"title": page["meta"].get("title", ""),
|
|
803
|
+
"confidence": conf,
|
|
804
|
+
"lifecycle": page["meta"].get("lifecycle", ""),
|
|
805
|
+
})
|
|
806
|
+
|
|
807
|
+
results.sort(key=lambda r: r["confidence"])
|
|
808
|
+
text = f"{len(results)} pages with confidence in [{min_c}, {max_c}]:\n\n"
|
|
809
|
+
for r in results[:50]:
|
|
810
|
+
text += f" {r['confidence']:.2f} {r['path']} — {r['title']}\n"
|
|
811
|
+
if len(results) > 50:
|
|
812
|
+
text += f"\n ... and {len(results) - 50} more\n"
|
|
813
|
+
return _ok(text)
|
|
814
|
+
|
|
815
|
+
|
|
816
|
+
def tool_wiki_lifecycle(args: dict[str, Any]) -> dict[str, Any]:
|
|
817
|
+
"""List pages filtered by lifecycle state (v1.0 · #159)."""
|
|
818
|
+
from sessionwiki.lint import load_pages
|
|
819
|
+
|
|
820
|
+
state = (args.get("state") or "").strip().lower()
|
|
821
|
+
if not state:
|
|
822
|
+
return _err("state is required")
|
|
823
|
+
|
|
824
|
+
wiki = REPO_ROOT / "wiki"
|
|
825
|
+
pages = load_pages(wiki)
|
|
826
|
+
|
|
827
|
+
matches = [
|
|
828
|
+
(rel, page["meta"].get("title", ""), page["meta"].get("last_updated", ""))
|
|
829
|
+
for rel, page in pages.items()
|
|
830
|
+
if page["meta"].get("lifecycle", "").lower() == state
|
|
831
|
+
]
|
|
832
|
+
matches.sort(key=lambda m: m[2], reverse=True)
|
|
833
|
+
|
|
834
|
+
text = f"{len(matches)} pages in lifecycle '{state}':\n\n"
|
|
835
|
+
for rel, title, updated in matches[:50]:
|
|
836
|
+
text += f" {updated} {rel} — {title}\n"
|
|
837
|
+
if len(matches) > 50:
|
|
838
|
+
text += f"\n ... and {len(matches) - 50} more\n"
|
|
839
|
+
return _ok(text)
|
|
840
|
+
|
|
841
|
+
|
|
842
|
+
def tool_wiki_dashboard(args: dict[str, Any]) -> dict[str, Any]:
|
|
843
|
+
"""Return wiki health summary (v1.0 · #159)."""
|
|
844
|
+
from sessionwiki.lint import load_pages
|
|
845
|
+
|
|
846
|
+
wiki = REPO_ROOT / "wiki"
|
|
847
|
+
pages = load_pages(wiki)
|
|
848
|
+
|
|
849
|
+
by_type: dict[str, int] = {}
|
|
850
|
+
by_lifecycle: dict[str, int] = {}
|
|
851
|
+
conf_buckets = {"high (≥0.8)": 0, "medium (0.5-0.8)": 0, "low (<0.5)": 0, "none": 0}
|
|
852
|
+
|
|
853
|
+
for page in pages.values():
|
|
854
|
+
meta = page["meta"]
|
|
855
|
+
t = meta.get("type", "unknown")
|
|
856
|
+
by_type[t] = by_type.get(t, 0) + 1
|
|
857
|
+
lc = meta.get("lifecycle", "none")
|
|
858
|
+
by_lifecycle[lc] = by_lifecycle.get(lc, 0) + 1
|
|
859
|
+
|
|
860
|
+
conf_raw = meta.get("confidence", "")
|
|
861
|
+
if not conf_raw:
|
|
862
|
+
conf_buckets["none"] += 1
|
|
863
|
+
else:
|
|
864
|
+
try:
|
|
865
|
+
c = float(conf_raw)
|
|
866
|
+
if c >= 0.8:
|
|
867
|
+
conf_buckets["high (≥0.8)"] += 1
|
|
868
|
+
elif c >= 0.5:
|
|
869
|
+
conf_buckets["medium (0.5-0.8)"] += 1
|
|
870
|
+
else:
|
|
871
|
+
conf_buckets["low (<0.5)"] += 1
|
|
872
|
+
except (ValueError, TypeError):
|
|
873
|
+
conf_buckets["none"] += 1
|
|
874
|
+
|
|
875
|
+
lines = [f"# Wiki Dashboard — {len(pages)} pages\n"]
|
|
876
|
+
lines.append("## By type\n")
|
|
877
|
+
for t in sorted(by_type):
|
|
878
|
+
lines.append(f" {by_type[t]:4d} {t}")
|
|
879
|
+
lines.append("\n## By lifecycle\n")
|
|
880
|
+
for lc in sorted(by_lifecycle):
|
|
881
|
+
lines.append(f" {by_lifecycle[lc]:4d} {lc}")
|
|
882
|
+
lines.append("\n## Confidence distribution\n")
|
|
883
|
+
for bucket in ["high (≥0.8)", "medium (0.5-0.8)", "low (<0.5)", "none"]:
|
|
884
|
+
lines.append(f" {conf_buckets[bucket]:4d} {bucket}")
|
|
885
|
+
|
|
886
|
+
return _ok("\n".join(lines))
|
|
887
|
+
|
|
888
|
+
|
|
889
|
+
def tool_wiki_entity_search(args: dict[str, Any]) -> dict[str, Any]:
|
|
890
|
+
"""Search entities by name or entity_type (v1.0 · #159)."""
|
|
891
|
+
from sessionwiki.lint import load_pages
|
|
892
|
+
|
|
893
|
+
name_q = (args.get("name") or "").strip().lower()
|
|
894
|
+
etype_q = (args.get("entity_type") or "").strip().lower()
|
|
895
|
+
|
|
896
|
+
wiki = REPO_ROOT / "wiki"
|
|
897
|
+
pages = load_pages(wiki)
|
|
898
|
+
|
|
899
|
+
matches: list[dict[str, Any]] = []
|
|
900
|
+
for rel, page in pages.items():
|
|
901
|
+
meta = page["meta"]
|
|
902
|
+
if meta.get("type") != "entity":
|
|
903
|
+
continue
|
|
904
|
+
title = meta.get("title", "")
|
|
905
|
+
etype = meta.get("entity_type", "").lower()
|
|
906
|
+
if name_q and name_q not in title.lower() and name_q not in rel.lower():
|
|
907
|
+
continue
|
|
908
|
+
if etype_q and etype_q != etype:
|
|
909
|
+
continue
|
|
910
|
+
matches.append({
|
|
911
|
+
"path": rel,
|
|
912
|
+
"title": title,
|
|
913
|
+
"entity_type": etype,
|
|
914
|
+
"confidence": meta.get("confidence", ""),
|
|
915
|
+
})
|
|
916
|
+
|
|
917
|
+
matches.sort(key=lambda m: m["title"])
|
|
918
|
+
text = f"{len(matches)} matching entities:\n\n"
|
|
919
|
+
for m in matches[:50]:
|
|
920
|
+
text += f" [{m['entity_type']:10}] {m['path']} — {m['title']}\n"
|
|
921
|
+
if len(matches) > 50:
|
|
922
|
+
text += f"\n ... and {len(matches) - 50} more\n"
|
|
923
|
+
return _ok(text)
|
|
924
|
+
|
|
925
|
+
|
|
926
|
+
def tool_wiki_category_browse(args: dict[str, Any]) -> dict[str, Any]:
|
|
927
|
+
"""Browse tags / categories (v1.0 · #159)."""
|
|
928
|
+
from sessionwiki.categories import scan_tags
|
|
929
|
+
from sessionwiki.lint import load_pages
|
|
930
|
+
|
|
931
|
+
tag = (args.get("tag") or "").strip().lower()
|
|
932
|
+
min_count = int(args.get("min_count", 1))
|
|
933
|
+
|
|
934
|
+
wiki = REPO_ROOT / "wiki"
|
|
935
|
+
pages = load_pages(wiki)
|
|
936
|
+
tags = scan_tags(pages)
|
|
937
|
+
|
|
938
|
+
if tag:
|
|
939
|
+
page_rels = tags.get(tag, [])
|
|
940
|
+
text = f"{len(page_rels)} pages tagged '{tag}':\n\n"
|
|
941
|
+
for rel in page_rels[:50]:
|
|
942
|
+
title = pages[rel]["meta"].get("title", "")
|
|
943
|
+
text += f" {rel} — {title}\n"
|
|
944
|
+
return _ok(text)
|
|
945
|
+
|
|
946
|
+
# List all tags with counts
|
|
947
|
+
filtered = [(t, len(pgs)) for t, pgs in tags.items() if len(pgs) >= min_count]
|
|
948
|
+
filtered.sort(key=lambda x: x[1], reverse=True)
|
|
949
|
+
|
|
950
|
+
text = f"{len(filtered)} tags with >= {min_count} pages:\n\n"
|
|
951
|
+
for t, count in filtered[:100]:
|
|
952
|
+
text += f" {count:4d} {t}\n"
|
|
953
|
+
return _ok(text)
|
|
954
|
+
|
|
955
|
+
|
|
956
|
+
TOOL_IMPLS = {
|
|
957
|
+
"wiki_query": tool_wiki_query,
|
|
958
|
+
"wiki_search": tool_wiki_search,
|
|
959
|
+
"wiki_list_sources": tool_wiki_list_sources,
|
|
960
|
+
"wiki_read_page": tool_wiki_read_page,
|
|
961
|
+
"wiki_lint": tool_wiki_lint,
|
|
962
|
+
"wiki_sync": tool_wiki_sync,
|
|
963
|
+
"wiki_export": tool_wiki_export,
|
|
964
|
+
# v1.0 (#159)
|
|
965
|
+
"wiki_confidence": tool_wiki_confidence,
|
|
966
|
+
"wiki_lifecycle": tool_wiki_lifecycle,
|
|
967
|
+
"wiki_dashboard": tool_wiki_dashboard,
|
|
968
|
+
"wiki_entity_search": tool_wiki_entity_search,
|
|
969
|
+
"wiki_category_browse": tool_wiki_category_browse,
|
|
970
|
+
}
|
|
971
|
+
|
|
972
|
+
|
|
973
|
+
# ─── JSON-RPC plumbing ────────────────────────────────────────────────────
|
|
974
|
+
|
|
975
|
+
|
|
976
|
+
def handle_initialize(params: dict[str, Any]) -> dict[str, Any]:
|
|
977
|
+
return {
|
|
978
|
+
"protocolVersion": PROTOCOL_VERSION,
|
|
979
|
+
"serverInfo": SERVER_INFO,
|
|
980
|
+
"capabilities": {"tools": {}},
|
|
981
|
+
}
|
|
982
|
+
|
|
983
|
+
|
|
984
|
+
def handle_tools_list(params: dict[str, Any]) -> dict[str, Any]:
|
|
985
|
+
return {"tools": TOOLS}
|
|
986
|
+
|
|
987
|
+
|
|
988
|
+
def handle_tools_call(params: dict[str, Any]) -> dict[str, Any]:
|
|
989
|
+
name = params.get("name")
|
|
990
|
+
args = params.get("arguments", {}) or {}
|
|
991
|
+
impl = TOOL_IMPLS.get(name)
|
|
992
|
+
if impl is None:
|
|
993
|
+
return _err(f"Unknown tool: {name}")
|
|
994
|
+
try:
|
|
995
|
+
return impl(args)
|
|
996
|
+
except Exception as e:
|
|
997
|
+
return _err(f"Internal error in {name}: {e}")
|
|
998
|
+
|
|
999
|
+
|
|
1000
|
+
HANDLERS = {
|
|
1001
|
+
"initialize": handle_initialize,
|
|
1002
|
+
"tools/list": handle_tools_list,
|
|
1003
|
+
"tools/call": handle_tools_call,
|
|
1004
|
+
}
|
|
1005
|
+
|
|
1006
|
+
|
|
1007
|
+
def send(message: dict[str, Any]) -> None:
|
|
1008
|
+
sys.stdout.write(json.dumps(message) + "\n")
|
|
1009
|
+
sys.stdout.flush()
|
|
1010
|
+
|
|
1011
|
+
|
|
1012
|
+
def error_response(req_id: Any, code: int, message: str) -> dict[str, Any]:
|
|
1013
|
+
return {
|
|
1014
|
+
"jsonrpc": "2.0",
|
|
1015
|
+
"id": req_id,
|
|
1016
|
+
"error": {"code": code, "message": message},
|
|
1017
|
+
}
|
|
1018
|
+
|
|
1019
|
+
|
|
1020
|
+
def main() -> int:
|
|
1021
|
+
"""Run the MCP server on stdin/stdout."""
|
|
1022
|
+
try:
|
|
1023
|
+
for line in sys.stdin:
|
|
1024
|
+
line = line.strip()
|
|
1025
|
+
if not line:
|
|
1026
|
+
continue
|
|
1027
|
+
try:
|
|
1028
|
+
req = json.loads(line)
|
|
1029
|
+
except json.JSONDecodeError:
|
|
1030
|
+
send(error_response(None, -32700, "Parse error"))
|
|
1031
|
+
continue
|
|
1032
|
+
|
|
1033
|
+
method = req.get("method", "")
|
|
1034
|
+
req_id = req.get("id")
|
|
1035
|
+
params = req.get("params", {}) or {}
|
|
1036
|
+
|
|
1037
|
+
handler = HANDLERS.get(method)
|
|
1038
|
+
if handler is None:
|
|
1039
|
+
if req_id is None:
|
|
1040
|
+
continue # notifications don't get a response
|
|
1041
|
+
send(error_response(req_id, -32601, f"Method not found: {method}"))
|
|
1042
|
+
continue
|
|
1043
|
+
|
|
1044
|
+
try:
|
|
1045
|
+
result = handler(params)
|
|
1046
|
+
except Exception as e:
|
|
1047
|
+
send(error_response(req_id, -32603, f"Internal error: {e}"))
|
|
1048
|
+
continue
|
|
1049
|
+
|
|
1050
|
+
if req_id is not None:
|
|
1051
|
+
send({"jsonrpc": "2.0", "id": req_id, "result": result})
|
|
1052
|
+
except KeyboardInterrupt:
|
|
1053
|
+
return 0
|
|
1054
|
+
except Exception as e:
|
|
1055
|
+
sys.stderr.write(f"MCP server error: {e}\n")
|
|
1056
|
+
return 1
|
|
1057
|
+
return 0
|
|
1058
|
+
|
|
1059
|
+
|
|
1060
|
+
if __name__ == "__main__":
|
|
1061
|
+
sys.exit(main())
|