Knowledge-to-Action MCP

1# Knowledge-to-Action MCP
2 
3> Turn Obsidian notes into agent-ready context, preview-only plans, and safe repo handoffs.
4 
5[![CI](https://github.com/tac0de/knowledge-to-action-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/tac0de/knowledge-to-action-mcp/actions/workflows/ci.yml)
6[![npm version](https://img.shields.io/npm/v/%40tac0de%2Fknowledge-to-action-mcp)](https://www.npmjs.com/package/@tac0de/knowledge-to-action-mcp)
7[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
8 
9![Knowledge-to-Action MCP](./github-thumbnail.png)
10 
11`knowledge-to-action-mcp` is an MCP server for people whose real project context lives in notes, decisions, roadmaps, and meeting docs, not just code.
12 
13Most Obsidian MCP servers stop at "read a note" or "search a vault."
14 
15This one goes further:
16 
17```text
18notes -> retrieval -> context packet -> action plan -> repo handoff
19```
20 
21That means an MCP client can move from:
22 
23```text
24"open this markdown file"
25```
26 
27to:
28 
29```text
30"understand the note, pull nearby context, summarize risks,
31propose next steps, and show which repo files probably matter"
32```
33 
34## Why It Matters
35 
36If you work out of Obsidian, your important context is usually spread across:
37 
38- roadmap notes
39- meeting notes
40- decisions
41- linked references
42- repo assumptions
43 
44Normal note integrations make an agent read those files.
45 
46`knowledge-to-action-mcp` helps an agent recover the surrounding context and turn it into something actionable without exposing a general shell runner.
47 
48## What Makes It Different
49 
50| Capability | Typical vault MCP | `knowledge-to-action-mcp` |
51| --- | --- | --- |
52| Read notes | Yes | Yes |
53| Search notes | Yes | Yes |
54| Follow links / backlinks | Sometimes | Yes |
55| Graph-aware context recovery | Rarely | Yes |
56| Optional embeddings | Rarely | Yes |
57| Agent-ready context packet | No | Yes |
58| Preview-only plan from note | No | Yes |
59| Note-to-repo handoff | No | Yes |
60| General shell access | Sometimes | No |
61 
62## 1-Minute Quickstart
63 
64Install:
65 
66```bash
67npm install @tac0de/knowledge-to-action-mcp
68```
69 
70Run in graph-only mode:
71 
72```bash
73OBSIDIAN_VAULT_ROOT="/path/to/vault" \
74npx @tac0de/knowledge-to-action-mcp
75```
76 
77Turn on optional embeddings and planning:
78 
79```bash
80OBSIDIAN_VAULT_ROOT="/path/to/vault" \
81EMBEDDINGS_ENABLED=true \
82PLANNING_ENABLED=true \
83OPENAI_API_KEY="..." \
84npx @tac0de/knowledge-to-action-mcp
85```
86 
87Then call:
88 
89- `context.retrieve`
90- `context.bundle_for_agent`
91- `action.plan_from_note`
92- `action.handoff_to_repo`
93 
94See also:
95 
96- sample vault: [`examples/sample-vault/`](./examples/sample-vault/)
97- sample outputs: [`examples/sample-output/`](./examples/sample-output/)
98- Claude Desktop config example: [`examples/claude-desktop-config.json`](./examples/claude-desktop-config.json)
99- VS Code config example: [`examples/vscode-mcp.json`](./examples/vscode-mcp.json)
100- Cursor config example: [`examples/cursor-mcp.json`](./examples/cursor-mcp.json)
101 
102## What You Actually Get
103 
104### 1. Obsidian-aware retrieval
105 
106- deterministic note listing, reading, and search
107- wikilink resolution
108- backlinks
109- shared-tag neighbors
110- graph-aware context recovery
111 
112### 2. Optional GraphRAG
113 
114When embeddings are enabled, retrieval becomes:
115 
116```text
117lexical + graph + semantic rerank
118```
119 
120No external graph database is required.
121 
122### 3. Agent-ready context packets
123 
124`context.bundle_for_agent` returns a structured packet instead of dumping raw markdown into a prompt.
125 
126That packet includes:
127 
128- brief
129- key facts
130- open questions
131- risks
132- related notes
133- repo hints
134 
135### 4. Preview-only action planning
136 
137`action.plan_from_note` turns a note into:
138 
139- summary
140- goals
141- constraints
142- decisions
143- open questions
144- suggested actions
145- handoff prompt
146 
147It does not mutate files.
148 
149### 5. Safe repo handoff
150 
151`action.handoff_to_repo` connects note context to a workspace using:
152 
153- bounded ripgrep queries
154- bounded git status
155- matched file suggestions
156 
157This is intentionally not a general-purpose shell runner.
158 
159## Example Workflow
160 
161Imagine you have these notes:
162 
163- `roadmap/search.md`
164- `meetings/2026-03-07-search-review.md`
165- `decisions/search-scope.md`
166 
167And a repo with:
168 
169- `src/search.ts`
170- `src/features/search/index.ts`
171 
172This MCP can help an agent:
173 
1741. Retrieve nearby notes with search, backlinks, tags, graph neighbors, and optional embeddings.
1752. Compress that note cluster into a structured context packet.
1763. Turn the source note into a preview-only action plan.
1774. Suggest likely repo files before any edit happens.
178 
179That jump from "read notes" to "prepare action safely" is the whole point.
180 
181## Demo Assets
182 
183If you want something concrete before wiring your own vault:
184 
185- sample vault notes live in [`examples/sample-vault/`](./examples/sample-vault/)
186- example `context.bundle_for_agent` output lives in [`examples/sample-output/context.bundle_for_agent.json`](./examples/sample-output/context.bundle_for_agent.json)
187- example `action.plan_from_note` output lives in [`examples/sample-output/action.plan_from_note.json`](./examples/sample-output/action.plan_from_note.json)
188- example Claude Desktop config lives in [`examples/claude-desktop-config.json`](./examples/claude-desktop-config.json)
189 
190## Public Tools
191 
192### Vault + Graph
193 
194- `vault.list_notes`
195- `vault.read_note`
196- `vault.search_notes`
197- `vault.get_metadata`
198- `graph.build`
199- `graph.get_neighbors`
200- `graph.get_backlinks`
201- `context.gather`
202 
203### Retrieval + Planning
204 
205- `embeddings.index_vault`
206- `context.retrieve`
207- `context.bundle_for_agent`
208- `action.plan_from_note`
209- `action.handoff_to_repo`
210 
211### Workspace Inspection
212 
213- `exec.list_capabilities`
214- `exec.rg_search`
215- `exec.list_dir`
216- `exec.git_status`
217 
218## Example Output
219 
220`context.bundle_for_agent`:
221 
222```json
223{
224  "brief": "Implement search using the existing dashboard flow.",
225  "source": "roadmap/search.md",
226  "keyFacts": [
227    "Title: Search",
228    "Tags: roadmap,search"
229  ],
230  "openQuestions": [
231    "Where is the current search entrypoint?"
232  ],
233  "risks": [
234    "Assumption: repo layout may differ from note context"
235  ],
236  "repoHints": {
237    "matchedFiles": [
238      "src/search.ts",
239      "src/features/search/index.ts"
240    ],
241    "suggestedQueries": [
242      "Search",
243      "search"
244    ]
245  }
246}
247```
248 
249`action.plan_from_note`:
250 
251```json
252{
253  "source": "roadmap/search.md",
254  "summary": "Implement search using the existing dashboard flow.",
255  "goals": [
256    "Ship dashboard search"
257  ],
258  "constraints": [
259    "No mutation without explicit approval"
260  ],
261  "openQuestions": [
262    "Where is the current search entrypoint?"
263  ],
264  "suggestedActions": [
265    "Review matched repo files",
266    "Resolve open questions before implementation"
267  ],
268  "generationMode": "deterministic"
269}
270```
271 
272## Configuration
273 
274### Required
275 
276- `OBSIDIAN_VAULT_ROOT`
277 
278### Optional embeddings
279 
280- `EMBEDDINGS_ENABLED=false`
281- `EMBEDDING_PROVIDER=openai`
282- `EMBEDDING_MODEL=text-embedding-3-small`
283- `EMBEDDING_SQLITE_PATH=.knowledge-to-action-mcp/index.sqlite`
284- `OPENAI_API_KEY=...`
285 
286### Optional planning
287 
288- `PLANNING_ENABLED=false`
289- `PLANNING_PROVIDER=openai`
290- `PLANNING_MODEL=gpt-4.1-mini`
291 
292### Optional workspace inspection
293 
294- `EXECUTION_ENABLED=false`
295- `EXECUTION_CAPABILITIES=workspace.search,workspace.inspect,workspace.git_status`
296- `EXECUTION_TIMEOUT_MS=5000`
297- `EXECUTION_MAX_OUTPUT_BYTES=32768`
298 
299## Install In MCP Clients
300 
301Example stdio config:
302 
303```json
304{
305  "command": "npx",
306  "args": ["-y", "@tac0de/knowledge-to-action-mcp"],
307  "env": {
308    "OBSIDIAN_VAULT_ROOT": "/path/to/vault"
309  }
310}
311```
312 
313### VS Code
314 
315Add to `.vscode/mcp.json`:
316 
317```json
318{
319  "servers": {
320    "knowledge-to-action": {
321      "command": "npx",
322      "args": ["-y", "@tac0de/knowledge-to-action-mcp"],
323      "env": {
324        "OBSIDIAN_VAULT_ROOT": "/path/to/vault"
325      }
326    }
327  }
328}
329```
330 
331### Cursor
332 
333Add to `.cursor/mcp.json`:
334 
335```json
336{
337  "mcpServers": {
338    "knowledge-to-action": {
339      "command": "npx",
340      "args": ["-y", "@tac0de/knowledge-to-action-mcp"],
341      "env": {
342        "OBSIDIAN_VAULT_ROOT": "/path/to/vault"
343      }
344    }
345  }
346}
347```
348 
349## Security Boundary
350 
351This package is designed to be useful without turning into a local shell bomb.
352 
353- vault access is read-only
354- plan generation is preview-only
355- embeddings are optional and local
356- repo inspection is bounded to the configured working directory
357- no generic `bash.exec` or arbitrary command tool is exposed
358 
359## Good Fit
360 
361Use this project if you want:
362 
363- Obsidian-native GraphRAG
364- note-to-action workflows for agents
365- structured context instead of giant markdown dumps
366- repo-aware handoff without broad execution access
367 
368## Not Trying To Be
369 
370- a general purpose agent runtime
371- a write-enabled automation framework
372- a hosted knowledge platform
373- a vector database product
374 
375## Compatibility
376 
377- package name: `@tac0de/knowledge-to-action-mcp`
378- legacy CLI alias: `obsidian-mcp`
379- Node.js 20+
380 
381## Status
382 
383`v2.1.1` is usable now:
384 
385- typecheck passes
386- unit and integration tests pass
387- npm pack dry-run passes
388 
389The project is still early, but the main workflow is already working.
390 
391## License
392 
393MIT
394