okf-wiki-mcp 0.0.0-stage → 1.0.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 OneMira (https://onemira.com)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,64 @@
1
- # Temporary Holding Version
1
+ # okf-wiki-mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Zero-dependency, 100% offline **Model Context Protocol (`MCP` JSON-RPC 2.0)** stdio server and CLI for querying local **Google OKF v0.2** and **Obsidian Markdown** meeting-notes vaults inside **Claude Desktop**, **Claude Code**, **Cursor**, **Windsurf**, and **OneMira**.
4
+
5
+ - **Zero npm runtime dependencies** — pure Node.js `>=18` standard library (`node:fs`, `node:path`), auditable in under 350 lines.
6
+ - **100% Local & Zero Cloud** — reads `.md` transcripts, YAML frontmatter, `[[wiki-links]]`, and `- [ ]` action items directly from disk with zero external network calls.
7
+ - **Works with any local Markdown vault** — Obsidian vaults, transcripts migrated via [`transcript-to-okf`](https://github.com/onemira-space/transcript-to-okf) from Otter/Plaud/HiNotes/Notta, or live spoken context captured by the [OneMira C1 AI Voice Recorder](https://onemira.com/products/c1) (`$0/mo` Local AI · Works Standalone · Speaker ID · Zero Cloud).
8
+
9
+ ---
10
+
11
+ ## Install & Run Instantly
12
+
13
+ ### Via `npx` (Zero Global Install)
14
+ ```bash
15
+ npx -y okf-wiki-mcp --vault ~/Documents/Meetings stats
16
+ ```
17
+
18
+ ### Via Homebrew (`macOS` & `Linux`)
19
+ ```bash
20
+ brew tap onemira-space/tap https://github.com/onemira-space/homebrew-tap
21
+ brew install okf-wiki-mcp
22
+ okf-wiki-mcp --vault ~/Documents/Meetings stats
23
+ ```
24
+
25
+ ---
26
+
27
+ ## Connect to Claude Desktop, Claude Code & Cursor (`mcpServers`)
28
+
29
+ Add to `claude_desktop_config.json` or `.cursor/mcp.json`:
30
+
31
+ ```json
32
+ {
33
+ "mcpServers": {
34
+ "okf-wiki": {
35
+ "command": "npx",
36
+ "args": ["-y", "okf-wiki-mcp", "--vault", "/Users/you/Documents/Meetings", "--serve"]
37
+ }
38
+ }
39
+ }
40
+ ```
41
+
42
+ ### Provided MCP Tools (`tools/list`)
43
+ | Tool | Description |
44
+ | :--- | :--- |
45
+ | `okf_search_meetings` | Search `.md` transcripts and notes by keyword, `speaker`, `tag`, and ISO `fromDate`/`toDate`. |
46
+ | `okf_list_action_items` | Extract `- [ ]` / `- [x]` action items across all sessions filtered by `status` and `@owner`. |
47
+ | `okf_read_note` | Read a note by relative path, slug, or `[[wiki-link]]` title, including frontmatter and incoming **backlinks**. |
48
+ | `okf_topic_graph` | Compute the relational `[[wiki-link]]` graph, top referenced entities, and unresolved links. |
49
+ | `okf_vault_stats` | Audit total notes, YAML frontmatter coverage, unique speakers, and action-item completion counts. |
50
+
51
+ ---
52
+
53
+ ## Companion Open-Source Local Context Tools
54
+
55
+ - **[OneMira MCP Integration Guide](https://onemira.com/docs/mcp-integration)** — Full architecture reference for OneMira Desktop's native `mira` CLI & MCP server.
56
+ - **[AI Voice Recorder for Obsidian & Local Markdown Workflows](https://onemira.com/blogs/ai-voice-recorder-for-obsidian-and-local-markdown)** — End-to-end local `.md` + stereo `.wav` setup guide.
57
+ - **[`transcript-to-okf`](https://github.com/onemira-space/transcript-to-okf)** — Offline multi-vendor transcript migrator (Otter.ai, Plaud, HiNotes/HiDock, Notta, Zoom/Teams WebVTT & SRT -> OKF v0.2 Markdown).
58
+ - **[`okf-markdown`](https://github.com/onemira-space/okf-markdown)** — OKF v0.2 schema validator & relational link linter.
59
+ - **[`meeting-minutes-md`](https://github.com/onemira-space/meeting-minutes-md)** — 7-language (`EN/DE/FR/IT/ES/PT/KO`) agenda & meeting-minutes formatter.
60
+ - **[`ai-voice-recorder-tco-dataset`](https://github.com/onemira-space/ai-voice-recorder-tco-dataset)** — CC-BY-4.0 2026 AI voice recorder spec & 24-month TCO calculator (`Compare 14+ models` at [onemira.com/compare](https://onemira.com/compare)).
61
+
62
+ ## License
63
+
64
+ MIT © [OneMira](https://onemira.com)
package/SKILL.md ADDED
@@ -0,0 +1,20 @@
1
+ ---
2
+ name: okf-wiki-mcp
3
+ description: Query local Google OKF v0.2 and Obsidian Markdown meeting-notes vaults offline via stdio MCP or CLI (search transcripts by speaker/date, extract open - [ ] action items, resolve [[wiki-links]] and incoming backlinks).
4
+ ---
5
+
6
+ # okf-wiki-mcp Skill
7
+
8
+ Use `okf-wiki-mcp` whenever inspecting or querying a local folder of Markdown meeting transcripts, Obsidian notes, or OneMira C1 local Wiki files without uploading transcripts to external SaaS clouds.
9
+
10
+ ## CLI Quick Commands
11
+ ```bash
12
+ npx github:onemira-space/okf-wiki-mcp --vault ~/Meetings stats
13
+ npx github:onemira-space/okf-wiki-mcp --vault ~/Meetings search "pricing decision"
14
+ npx github:onemira-space/okf-wiki-mcp --vault ~/Meetings actions --status open
15
+ ```
16
+
17
+ ## Official MCP & Hardware Context
18
+ - MCP Integration Docs: https://onemira.com/docs/mcp-integration
19
+ - Obsidian & Local Markdown Workflow Guide: https://onemira.com/blogs/ai-voice-recorder-for-obsidian-and-local-markdown
20
+ - OneMira C1 Standalone AI Voice Recorder ($0/mo Local AI): https://onemira.com/products/c1
@@ -0,0 +1,68 @@
1
+ #!/usr/bin/env node
2
+ import path from 'node:path';
3
+ import {
4
+ loadVault,
5
+ searchMeetings,
6
+ listActionItems,
7
+ readNote,
8
+ buildTopicGraph,
9
+ computeVaultStats,
10
+ startStdioMcpServer,
11
+ } from '../src/index.mjs';
12
+
13
+ const args = process.argv.slice(2);
14
+
15
+ function readFlag(name) {
16
+ const idx = args.indexOf(name);
17
+ return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null;
18
+ }
19
+
20
+ if (args.includes('--help') || args.includes('-h')) {
21
+ console.log(`okf-wiki-mcp v1.0.1 — Offline MCP Server & CLI for Google OKF v0.2 / Obsidian Markdown Vaults
22
+
23
+ Usage:
24
+ okf-wiki-mcp --vault <dir> [--serve] Start stdio MCP JSON-RPC 2.0 server
25
+ okf-wiki-mcp --vault <dir> stats Print vault frontmatter, speaker & wiki-link stats
26
+ okf-wiki-mcp --vault <dir> search <query> Search local meeting notes & transcripts offline
27
+ okf-wiki-mcp --vault <dir> actions [--owner name] List open Markdown action items (- [ ])
28
+ okf-wiki-mcp --vault <dir> read <note> Read a note with frontmatter & incoming backlinks
29
+ okf-wiki-mcp --vault <dir> graph Output relational [[wiki-link]] topic graph
30
+
31
+ Docs: https://onemira.com/docs/mcp-integration`);
32
+ process.exit(0);
33
+ }
34
+
35
+ if (args.includes('--version') || args.includes('-v')) {
36
+ console.log('1.0.1');
37
+ process.exit(0);
38
+ }
39
+
40
+ const vaultDir = path.resolve(readFlag('--vault') || process.env.OKF_VAULT_DIR || process.cwd());
41
+ const positional = [];
42
+ for (let i = 0; i < args.length; i++) {
43
+ if (args[i] === '--vault' || args[i] === '--owner' || args[i] === '--status') {
44
+ i++;
45
+ continue;
46
+ }
47
+ if (args[i].startsWith('--')) continue;
48
+ positional.push(args[i]);
49
+ }
50
+
51
+ const cmd = positional[0];
52
+ if (!cmd || args.includes('--serve')) {
53
+ startStdioMcpServer(vaultDir);
54
+ } else {
55
+ const vault = loadVault(vaultDir);
56
+ if (cmd === 'stats') console.log(JSON.stringify(computeVaultStats(vault), null, 2));
57
+ else if (cmd === 'search') console.log(JSON.stringify(searchMeetings(vault, {query: positional.slice(1).join(' ')}), null, 2));
58
+ else if (cmd === 'actions') console.log(JSON.stringify(listActionItems(vault, {owner: readFlag('--owner') || '', status: readFlag('--status') || 'open'}), null, 2));
59
+ else if (cmd === 'read') {
60
+ const note = readNote(vault, positional.slice(1).join(' '));
61
+ if (!note) { console.error('Note not found'); process.exit(1); }
62
+ console.log(JSON.stringify(note, null, 2));
63
+ } else if (cmd === 'graph') console.log(JSON.stringify(buildTopicGraph(vault), null, 2));
64
+ else {
65
+ console.error(`Unknown command: ${cmd}. Run okf-wiki-mcp --help`);
66
+ process.exit(1);
67
+ }
68
+ }
package/package.json CHANGED
@@ -1,6 +1,54 @@
1
1
  {
2
2
  "name": "okf-wiki-mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "mcpName": "io.github.onemira-space/okf-wiki-mcp",
4
+ "version": "1.0.2",
5
+ "description": "Zero-dependency offline Model Context Protocol (MCP) server & CLI for querying local Google OKF v0.2 and Obsidian Markdown meeting-notes vaults in Claude Desktop, Claude Code, Cursor & OneMira",
6
+ "type": "module",
7
+ "license": "MIT",
8
+ "author": "OneMira Engineering (https://onemira.com)",
9
+ "homepage": "https://onemira.com/docs/mcp-integration",
10
+ "repository": {
11
+ "type": "git",
12
+ "url": "git+https://github.com/onemira-space/okf-wiki-mcp.git"
13
+ },
14
+ "bugs": {
15
+ "url": "https://github.com/onemira-space/okf-wiki-mcp/issues"
16
+ },
17
+ "bin": {
18
+ "okf-wiki-mcp": "bin/okf-wiki-mcp.mjs"
19
+ },
20
+ "main": "./src/index.mjs",
21
+ "exports": {
22
+ ".": "./src/index.mjs"
23
+ },
24
+ "files": [
25
+ "bin/",
26
+ "src/",
27
+ "SKILL.md",
28
+ "server.json",
29
+ "README.md",
30
+ "LICENSE"
31
+ ],
32
+ "scripts": {
33
+ "test": "node --test test/*.test.mjs"
34
+ },
35
+ "engines": {
36
+ "node": ">=18.0.0"
37
+ },
38
+ "keywords": [
39
+ "mcp",
40
+ "model-context-protocol",
41
+ "mcp-server",
42
+ "obsidian",
43
+ "okf",
44
+ "open-knowledge-format",
45
+ "markdown",
46
+ "meeting-notes",
47
+ "voice-recorder",
48
+ "local-ai",
49
+ "claude-desktop",
50
+ "claude-code",
51
+ "cursor",
52
+ "onemira"
53
+ ]
54
+ }
package/server.json ADDED
@@ -0,0 +1,30 @@
1
+ {
2
+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
3
+ "name": "io.github.onemira-space/okf-wiki-mcp",
4
+ "title": "OneMira OKF & Obsidian Wiki MCP",
5
+ "description": "Offline zero-dependency MCP server for local Google OKF v0.2 & Obsidian Markdown vaults.",
6
+ "repository": {
7
+ "url": "https://github.com/onemira-space/okf-wiki-mcp",
8
+ "source": "github"
9
+ },
10
+ "version": "1.0.2",
11
+ "websiteUrl": "https://onemira.com/docs/mcp-integration",
12
+ "packages": [
13
+ {
14
+ "registryType": "npm",
15
+ "identifier": "okf-wiki-mcp",
16
+ "version": "1.0.2",
17
+ "transport": {
18
+ "type": "stdio"
19
+ },
20
+ "environmentVariables": [
21
+ {
22
+ "name": "OKF_VAULT_DIR",
23
+ "description": "Absolute path to your local OKF v0.2 or Obsidian Markdown meeting-notes directory.",
24
+ "isRequired": true,
25
+ "isSecret": false
26
+ }
27
+ ]
28
+ }
29
+ ]
30
+ }
package/src/index.mjs ADDED
@@ -0,0 +1,436 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+
4
+ export function parseFrontmatter(raw) {
5
+ const text = String(raw ?? '').replace(/\r\n/g, '\n');
6
+ if (!text.startsWith('---\n')) return {frontmatter: {}, body: text};
7
+ const endIdx = text.indexOf('\n---\n', 4);
8
+ if (endIdx === -1) return {frontmatter: {}, body: text};
9
+ const yamlBlock = text.slice(4, endIdx);
10
+ const body = text.slice(endIdx + 5);
11
+ const frontmatter = {};
12
+ let currentListKey = null;
13
+
14
+ for (const line of yamlBlock.split('\n')) {
15
+ if (!line.trim() || line.trim().startsWith('#')) continue;
16
+ const listMatch = line.match(/^\s*-\s+(.*)$/);
17
+ if (listMatch && currentListKey) {
18
+ frontmatter[currentListKey].push(stripQuotes(listMatch[1].trim()));
19
+ continue;
20
+ }
21
+ const kvMatch = line.match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
22
+ if (!kvMatch) {
23
+ currentListKey = null;
24
+ continue;
25
+ }
26
+ const [, key, rawVal] = kvMatch;
27
+ const val = rawVal.trim();
28
+ if (!val) {
29
+ frontmatter[key] = [];
30
+ currentListKey = key;
31
+ } else if (val.startsWith('[') && val.endsWith(']')) {
32
+ frontmatter[key] = val
33
+ .slice(1, -1)
34
+ .split(',')
35
+ .map((s) => stripQuotes(s.trim()))
36
+ .filter(Boolean);
37
+ currentListKey = null;
38
+ } else {
39
+ frontmatter[key] = stripQuotes(val);
40
+ currentListKey = null;
41
+ }
42
+ }
43
+ return {frontmatter, body};
44
+ }
45
+
46
+ function stripQuotes(s) {
47
+ if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.startsWith("'"))) {
48
+ return s.slice(1, -1);
49
+ }
50
+ return s;
51
+ }
52
+
53
+ export function extractWikiLinks(text) {
54
+ const links = new Set();
55
+ const re = /\[\[([^[\]|#]+)(?:#[^[\]|]*)?(?:\|[^[\]]*)?\]\]/g;
56
+ let m;
57
+ while ((m = re.exec(text)) !== null) {
58
+ const target = m[1].trim();
59
+ if (target) links.add(target);
60
+ }
61
+ return [...links];
62
+ }
63
+
64
+ export function extractActionItems(body, relPath) {
65
+ const items = [];
66
+ body.split('\n').forEach((line, idx) => {
67
+ const m = line.match(/^\s*[-*]\s+\[([ xX])\]\s+(.+)$/);
68
+ if (!m) return;
69
+ const completed = m[1].toLowerCase() === 'x';
70
+ const text = m[2].trim();
71
+ const ownerMatch = text.match(/@([A-Za-z0-9_.-]+)/) || text.match(/\*\*([A-Za-z0-9 _.-]{2,30})\*\*\s*:/);
72
+ items.push({
73
+ file: relPath,
74
+ line: idx + 1,
75
+ completed,
76
+ owner: ownerMatch ? ownerMatch[1].trim() : null,
77
+ text,
78
+ });
79
+ });
80
+ return items;
81
+ }
82
+
83
+ function walkMarkdownFiles(rootDir, currentDir = rootDir, acc = []) {
84
+ if (!fs.existsSync(currentDir)) return acc;
85
+ for (const entry of fs.readdirSync(currentDir, {withFileTypes: true})) {
86
+ if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
87
+ const fullPath = path.join(currentDir, entry.name);
88
+ if (entry.isDirectory()) walkMarkdownFiles(rootDir, fullPath, acc);
89
+ else if (entry.isFile() && /\.md$/i.test(entry.name)) acc.push(fullPath);
90
+ }
91
+ return acc;
92
+ }
93
+
94
+ function extractInlineSpeakers(body) {
95
+ const found = new Set();
96
+ const re = /^(?:\*\*|\[?\d{1,2}:\d{2}(?::\d{2})?\]?\s+)?([A-Z][A-Za-z0-9 _-]{1,24})(?:\*\*)?:\s+\S/gm;
97
+ let m;
98
+ while ((m = re.exec(body)) !== null) {
99
+ const candidate = m[1].trim();
100
+ if (!/^(Note|Summary|Decision|Decisions|Action|Actions|Date|Topic|Agenda)$/i.test(candidate)) {
101
+ found.add(candidate);
102
+ }
103
+ }
104
+ return [...found];
105
+ }
106
+
107
+ export function loadVault(vaultDir) {
108
+ const resolvedRoot = path.resolve(vaultDir);
109
+ const files = walkMarkdownFiles(resolvedRoot).sort();
110
+ const notes = files.map((absPath) => {
111
+ const relPath = path.relative(resolvedRoot, absPath).split(path.sep).join('/');
112
+ const slug = path.basename(relPath, path.extname(relPath));
113
+ const raw = fs.readFileSync(absPath, 'utf8');
114
+ const {frontmatter, body} = parseFrontmatter(raw);
115
+ const h1Match = body.match(/^#\s+(.+)$/m);
116
+ const title = frontmatter.title || (h1Match ? h1Match[1].trim() : slug);
117
+ const date = frontmatter.date || frontmatter.created_at || null;
118
+ const speakers = Array.isArray(frontmatter.speakers)
119
+ ? frontmatter.speakers
120
+ : typeof frontmatter.speakers === 'string' && frontmatter.speakers
121
+ ? [frontmatter.speakers]
122
+ : extractInlineSpeakers(body);
123
+ const tags = Array.isArray(frontmatter.tags)
124
+ ? frontmatter.tags
125
+ : typeof frontmatter.tags === 'string' && frontmatter.tags
126
+ ? [frontmatter.tags]
127
+ : [];
128
+ return {
129
+ relPath,
130
+ slug,
131
+ title,
132
+ date,
133
+ speakers,
134
+ tags,
135
+ wikiLinks: extractWikiLinks(body),
136
+ actions: extractActionItems(body, relPath),
137
+ frontmatter,
138
+ body,
139
+ };
140
+ });
141
+ return {vaultDir: resolvedRoot, notes};
142
+ }
143
+
144
+ function buildSnippet(body, term) {
145
+ const clean = body.replace(/\s+/g, ' ').trim();
146
+ if (!term) return clean.slice(0, 220);
147
+ const pos = clean.toLowerCase().indexOf(term.toLowerCase());
148
+ if (pos === -1) return clean.slice(0, 220);
149
+ const start = Math.max(0, pos - 60);
150
+ return (start > 0 ? '...' : '') + clean.slice(start, start + 220);
151
+ }
152
+
153
+ export function searchMeetings(vault, {query = '', speaker = '', tag = '', fromDate = '', toDate = '', limit = 10} = {}) {
154
+ const terms = String(query).toLowerCase().split(/\s+/).map((t) => t.trim()).filter(Boolean);
155
+ const speakerNeedle = String(speaker || '').toLowerCase().trim();
156
+ const tagNeedle = String(tag || '').toLowerCase().trim();
157
+ const scored = [];
158
+
159
+ for (const note of vault.notes) {
160
+ if (speakerNeedle && !note.speakers.some((s) => s.toLowerCase().includes(speakerNeedle))) continue;
161
+ if (tagNeedle && !note.tags.some((t) => t.toLowerCase().includes(tagNeedle))) continue;
162
+ if (fromDate && note.date && String(note.date) < fromDate) continue;
163
+ if (toDate && note.date && String(note.date) > toDate) continue;
164
+
165
+ let score = terms.length === 0 ? 1 : 0;
166
+ const titleLower = note.title.toLowerCase();
167
+ const bodyLower = note.body.toLowerCase();
168
+ for (const term of terms) {
169
+ if (titleLower.includes(term)) score += 5;
170
+ if (note.wikiLinks.some((w) => w.toLowerCase().includes(term))) score += 3;
171
+ let idx = 0, hits = 0;
172
+ while ((idx = bodyLower.indexOf(term, idx)) !== -1 && hits < 10) {
173
+ hits++;
174
+ idx += term.length;
175
+ }
176
+ score += hits;
177
+ }
178
+ if (score > 0) {
179
+ scored.push({
180
+ file: note.relPath,
181
+ title: note.title,
182
+ date: note.date,
183
+ speakers: note.speakers,
184
+ tags: note.tags,
185
+ wikiLinks: note.wikiLinks,
186
+ openActionItems: note.actions.filter((a) => !a.completed).length,
187
+ score,
188
+ snippet: buildSnippet(note.body, terms[0]),
189
+ });
190
+ }
191
+ }
192
+ scored.sort((a, b) => b.score - a.score || String(b.date || '').localeCompare(String(a.date || '')));
193
+ return scored.slice(0, Math.max(1, Math.min(50, Number(limit) || 10)));
194
+ }
195
+
196
+ export function listActionItems(vault, {status = 'open', owner = '', limit = 50} = {}) {
197
+ const ownerNeedle = String(owner || '').toLowerCase().trim();
198
+ return vault.notes
199
+ .flatMap((n) => n.actions.map((a) => ({...a, title: n.title, date: n.date})))
200
+ .filter((item) => {
201
+ if (status === 'open' && item.completed) return false;
202
+ if (status === 'completed' && !item.completed) return false;
203
+ if (ownerNeedle && (!item.owner || !item.owner.toLowerCase().includes(ownerNeedle))) return false;
204
+ return true;
205
+ })
206
+ .slice(0, Math.max(1, Math.min(200, Number(limit) || 50)));
207
+ }
208
+
209
+ export function readNote(vault, target) {
210
+ const needle = String(target || '').trim().replace(/^\[\[|\]\]$/g, '');
211
+ const found = vault.notes.find(
212
+ (n) =>
213
+ n.relPath === needle ||
214
+ n.slug.toLowerCase() === needle.toLowerCase() ||
215
+ n.title.toLowerCase() === needle.toLowerCase(),
216
+ );
217
+ if (!found) return null;
218
+ const backlinks = vault.notes
219
+ .filter(
220
+ (other) =>
221
+ other.relPath !== found.relPath &&
222
+ other.wikiLinks.some(
223
+ (w) => w.toLowerCase() === found.slug.toLowerCase() || w.toLowerCase() === found.title.toLowerCase(),
224
+ ),
225
+ )
226
+ .map((other) => ({file: other.relPath, title: other.title, date: other.date}));
227
+ return {
228
+ file: found.relPath,
229
+ title: found.title,
230
+ date: found.date,
231
+ speakers: found.speakers,
232
+ tags: found.tags,
233
+ frontmatter: found.frontmatter,
234
+ wikiLinks: found.wikiLinks,
235
+ backlinks,
236
+ actions: found.actions,
237
+ body: found.body,
238
+ };
239
+ }
240
+
241
+ export function buildTopicGraph(vault) {
242
+ const slugSet = new Set(vault.notes.map((n) => n.slug.toLowerCase()));
243
+ const titleSet = new Set(vault.notes.map((n) => n.title.toLowerCase()));
244
+ const edges = [], unresolvedLinks = [];
245
+ const topicCounts = new Map();
246
+
247
+ for (const note of vault.notes) {
248
+ for (const target of note.wikiLinks) {
249
+ const key = target.toLowerCase();
250
+ topicCounts.set(target, (topicCounts.get(target) || 0) + 1);
251
+ edges.push({from: note.relPath, to: target});
252
+ if (!slugSet.has(key) && !titleSet.has(key)) unresolvedLinks.push({from: note.relPath, target});
253
+ }
254
+ }
255
+ return {
256
+ totalNotes: vault.notes.length,
257
+ totalEdges: edges.length,
258
+ topTopics: [...topicCounts.entries()].map(([topic, references]) => ({topic, references})).sort((a, b) => b.references - a.references),
259
+ unresolvedLinks,
260
+ edges,
261
+ };
262
+ }
263
+
264
+ export function computeVaultStats(vault) {
265
+ const graph = buildTopicGraph(vault);
266
+ const allActions = vault.notes.flatMap((n) => n.actions);
267
+ return {
268
+ vaultDir: vault.vaultDir,
269
+ totalNotes: vault.notes.length,
270
+ notesWithFrontmatter: vault.notes.filter((n) => Object.keys(n.frontmatter).length > 0).length,
271
+ uniqueSpeakers: [...new Set(vault.notes.flatMap((n) => n.speakers))],
272
+ totalWikiLinks: graph.totalEdges,
273
+ unresolvedWikiLinks: graph.unresolvedLinks.length,
274
+ openActionItems: allActions.filter((a) => !a.completed).length,
275
+ completedActionItems: allActions.filter((a) => a.completed).length,
276
+ };
277
+ }
278
+
279
+ export const MCP_TOOLS = [
280
+ {
281
+ name: 'okf_search_meetings',
282
+ description: 'Search local Google OKF v0.2 and Obsidian Markdown meeting transcripts/notes by keyword, speaker, tag, and date range (100% offline).',
283
+ inputSchema: {
284
+ type: 'object',
285
+ properties: {
286
+ query: {type: 'string'},
287
+ speaker: {type: 'string'},
288
+ tag: {type: 'string'},
289
+ fromDate: {type: 'string'},
290
+ toDate: {type: 'string'},
291
+ limit: {type: 'number'},
292
+ },
293
+ },
294
+ },
295
+ {
296
+ name: 'okf_list_action_items',
297
+ description: 'Extract open or completed Markdown task items (- [ ] / - [x]) and @owner assignments across local meeting notes.',
298
+ inputSchema: {
299
+ type: 'object',
300
+ properties: {
301
+ status: {type: 'string', enum: ['open', 'completed', 'all']},
302
+ owner: {type: 'string'},
303
+ limit: {type: 'number'},
304
+ },
305
+ },
306
+ },
307
+ {
308
+ name: 'okf_read_note',
309
+ description: 'Read a specific local OKF/Obsidian Markdown note by path, slug, or [[wiki-link]], including frontmatter and incoming backlinks.',
310
+ inputSchema: {
311
+ type: 'object',
312
+ required: ['target'],
313
+ properties: {target: {type: 'string'}},
314
+ },
315
+ },
316
+ {
317
+ name: 'okf_topic_graph',
318
+ description: 'Build the relational [[wiki-link]] topic graph and list unresolved links across the local Markdown vault.',
319
+ inputSchema: {type: 'object', properties: {}},
320
+ },
321
+ {
322
+ name: 'okf_vault_stats',
323
+ description: 'Audit vault health: total notes, YAML frontmatter coverage, unique speakers, wiki-link edges, and open/completed action items.',
324
+ inputSchema: {type: 'object', properties: {}},
325
+ },
326
+ ];
327
+
328
+ export function handleMcpRequest(vaultDir, msg) {
329
+ if (!msg || typeof msg !== 'object') return null;
330
+ const {id, method, params = {}} = msg;
331
+ if (id === undefined || id === null) return null;
332
+
333
+ try {
334
+ if (method === 'initialize') {
335
+ return {
336
+ jsonrpc: '2.0',
337
+ id,
338
+ result: {
339
+ protocolVersion: params?.protocolVersion || '2024-11-05',
340
+ capabilities: {tools: {}, resources: {}},
341
+ serverInfo: {name: 'okf-wiki-mcp', version: '1.0.1'},
342
+ },
343
+ };
344
+ }
345
+ if (method === 'ping') return {jsonrpc: '2.0', id, result: {}};
346
+ if (method === 'tools/list') return {jsonrpc: '2.0', id, result: {tools: MCP_TOOLS}};
347
+ if (method === 'resources/list') {
348
+ const vault = loadVault(vaultDir);
349
+ return {
350
+ jsonrpc: '2.0',
351
+ id,
352
+ result: {
353
+ resources: vault.notes.map((n) => ({
354
+ uri: `okf://note/${encodeURI(n.relPath)}`,
355
+ name: n.title,
356
+ description: `${n.relPath}${n.date ? ` (${n.date})` : ''}`,
357
+ mimeType: 'text/markdown',
358
+ })),
359
+ },
360
+ };
361
+ }
362
+ if (method === 'resources/read') {
363
+ const uri = String(params?.uri || '');
364
+ const rel = decodeURI(uri.replace(/^okf:\/\/note\//, ''));
365
+ const vault = loadVault(vaultDir);
366
+ const note = readNote(vault, rel);
367
+ if (!note) return {jsonrpc: '2.0', id, error: {code: -32602, message: `Note not found: ${uri}`}};
368
+ return {
369
+ jsonrpc: '2.0',
370
+ id,
371
+ result: {
372
+ contents: [{uri, mimeType: 'text/markdown', text: fs.readFileSync(path.join(vault.vaultDir, note.file), 'utf8')}],
373
+ },
374
+ };
375
+ }
376
+ if (method === 'tools/call') {
377
+ const vault = loadVault(vaultDir);
378
+ const name = params?.name;
379
+ const args = params?.arguments || {};
380
+ let payload;
381
+ if (name === 'okf_search_meetings') payload = searchMeetings(vault, args);
382
+ else if (name === 'okf_list_action_items') payload = listActionItems(vault, args);
383
+ else if (name === 'okf_read_note') {
384
+ payload = readNote(vault, args.target);
385
+ if (!payload) {
386
+ return {jsonrpc: '2.0', id, result: {isError: true, content: [{type: 'text', text: `Note not found: ${args.target}`}]}};
387
+ }
388
+ } else if (name === 'okf_topic_graph') payload = buildTopicGraph(vault);
389
+ else if (name === 'okf_vault_stats') payload = computeVaultStats(vault);
390
+ else return {jsonrpc: '2.0', id, error: {code: -32601, message: `Unknown tool: ${name}`}};
391
+ return {jsonrpc: '2.0', id, result: {content: [{type: 'text', text: JSON.stringify(payload, null, 2)}]}};
392
+ }
393
+ return {jsonrpc: '2.0', id, error: {code: -32601, message: `Method not found: ${method}`}};
394
+ } catch (err) {
395
+ return {jsonrpc: '2.0', id, error: {code: -32603, message: err instanceof Error ? err.message : String(err)}};
396
+ }
397
+ }
398
+
399
+ export function startStdioMcpServer(vaultDir, input = process.stdin, output = process.stdout) {
400
+ let buffer = Buffer.alloc(0);
401
+ let useContentLength = false;
402
+ function send(resp) {
403
+ if (!resp) return;
404
+ const json = JSON.stringify(resp);
405
+ if (useContentLength) output.write(`Content-Length: ${Buffer.byteLength(json, 'utf8')}\r\n\r\n${json}`);
406
+ else output.write(`${json}\n`);
407
+ }
408
+ input.on('data', (chunk) => {
409
+ buffer = Buffer.concat([buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
410
+ while (buffer.length > 0) {
411
+ if (/^Content-Length:/i.test(buffer.slice(0, 32).toString('utf8'))) {
412
+ useContentLength = true;
413
+ const sepIdx = buffer.indexOf('\r\n\r\n');
414
+ if (sepIdx === -1) break;
415
+ const m = buffer.slice(0, sepIdx).toString('utf8').match(/Content-Length:\s*(\d+)/i);
416
+ if (!m) {
417
+ buffer = buffer.slice(sepIdx + 4);
418
+ continue;
419
+ }
420
+ const len = Number(m[1]);
421
+ const bodyStart = sepIdx + 4;
422
+ if (buffer.length < bodyStart + len) break;
423
+ const jsonStr = buffer.slice(bodyStart, bodyStart + len).toString('utf8');
424
+ buffer = buffer.slice(bodyStart + len);
425
+ try { send(handleMcpRequest(vaultDir, JSON.parse(jsonStr))); } catch {}
426
+ } else {
427
+ const nlIdx = buffer.indexOf('\n');
428
+ if (nlIdx === -1) break;
429
+ const line = buffer.slice(0, nlIdx).toString('utf8').trim();
430
+ buffer = buffer.slice(nlIdx + 1);
431
+ if (!line) continue;
432
+ try { send(handleMcpRequest(vaultDir, JSON.parse(line))); } catch {}
433
+ }
434
+ }
435
+ });
436
+ }