Knowledge-to-Action MCP

Turn Obsidian notes into agent-ready context, preview-only plans, and safe repo handoffs.

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.

Most Obsidian MCP servers stop at "read a note" or "search a vault."

This one goes further:

notes -> retrieval -> context packet -> action plan -> repo handoff

That means an MCP client can move from:

"open this markdown file"

to:

"understand the note, pull nearby context, summarize risks,
propose next steps, and show which repo files probably matter"

Why It Matters

If you work out of Obsidian, your important context is usually spread across:

• roadmap notes

• meeting notes

• decisions

• linked references

• repo assumptions

Normal note integrations make an agent read those files.

knowledge-to-action-mcp helps an agent recover the surrounding context and turn it into something actionable without exposing a general shell runner.

What Makes It Different

1-Minute Quickstart

Install:

npm install @tac0de/knowledge-to-action-mcp

Run in graph-only mode:

OBSIDIAN_VAULT_ROOT="/path/to/vault" \
npx @tac0de/knowledge-to-action-mcp

Turn on optional embeddings and planning:

OBSIDIAN_VAULT_ROOT="/path/to/vault" \
EMBEDDINGS_ENABLED=true \
PLANNING_ENABLED=true \
OPENAI_API_KEY="..." \
npx @tac0de/knowledge-to-action-mcp

Then call:

• context.retrieve

• context.bundle_for_agent

• action.plan_from_note

• action.handoff_to_repo

See also:

• sample vault: examples/sample-vault/

• sample outputs: examples/sample-output/

• Claude Desktop config example: examples/claude-desktop-config.json

• VS Code config example: examples/vscode-mcp.json

• Cursor config example: examples/cursor-mcp.json

What You Actually Get

1. Obsidian-aware retrieval

• deterministic note listing, reading, and search

• wikilink resolution

• backlinks

• shared-tag neighbors

• graph-aware context recovery

2. Optional GraphRAG

When embeddings are enabled, retrieval becomes:

lexical + graph + semantic rerank

No external graph database is required.

3. Agent-ready context packets

context.bundle_for_agent returns a structured packet instead of dumping raw markdown into a prompt.

That packet includes:

• brief

• key facts

• open questions

• risks

• related notes

• repo hints

4. Preview-only action planning

action.plan_from_note turns a note into:

• summary

• goals

• constraints

• decisions

• open questions

• suggested actions

• handoff prompt

It does not mutate files.

5. Safe repo handoff

action.handoff_to_repo connects note context to a workspace using:

• bounded ripgrep queries

• bounded git status

• matched file suggestions

This is intentionally not a general-purpose shell runner.

Example Workflow

Imagine you have these notes:

• roadmap/search.md

• meetings/2026-03-07-search-review.md

• decisions/search-scope.md

And a repo with:

• src/search.ts

• src/features/search/index.ts

This MCP can help an agent:

1. Retrieve nearby notes with search, backlinks, tags, graph neighbors, and optional embeddings.

2. Compress that note cluster into a structured context packet.

3. Turn the source note into a preview-only action plan.

4. Suggest likely repo files before any edit happens.

That jump from "read notes" to "prepare action safely" is the whole point.

Demo Assets

If you want something concrete before wiring your own vault:

• sample vault notes live in examples/sample-vault/

• example context.bundle_for_agent output lives in examples/sample-output/context.bundle_for_agent.json

• example action.plan_from_note output lives in examples/sample-output/action.plan_from_note.json

• example Claude Desktop config lives in examples/claude-desktop-config.json

Public Tools

Vault + Graph

• vault.list_notes

• vault.read_note

• vault.search_notes

• vault.get_metadata

• graph.build

• graph.get_neighbors

• graph.get_backlinks

• context.gather

Retrieval + Planning

• embeddings.index_vault

• context.retrieve

• context.bundle_for_agent

• action.plan_from_note

• action.handoff_to_repo

Workspace Inspection

• exec.list_capabilities

• exec.rg_search

• exec.list_dir

• exec.git_status

Example Output

context.bundle_for_agent:

{
  "brief": "Implement search using the existing dashboard flow.",
  "source": "roadmap/search.md",
  "keyFacts": [
    "Title: Search",
    "Tags: roadmap,search"
  ],
  "openQuestions": [
    "Where is the current search entrypoint?"
  ],
  "risks": [
    "Assumption: repo layout may differ from note context"
  ],
  "repoHints": {
    "matchedFiles": [
      "src/search.ts",
      "src/features/search/index.ts"
    ],
    "suggestedQueries": [
      "Search",
      "search"
    ]
  }
}

action.plan_from_note:

{
  "source": "roadmap/search.md",
  "summary": "Implement search using the existing dashboard flow.",
  "goals": [
    "Ship dashboard search"
  ],
  "constraints": [
    "No mutation without explicit approval"
  ],
  "openQuestions": [
    "Where is the current search entrypoint?"
  ],
  "suggestedActions": [
    "Review matched repo files",
    "Resolve open questions before implementation"
  ],
  "generationMode": "deterministic"
}

Configuration

Required

• OBSIDIAN_VAULT_ROOT

Optional embeddings

• EMBEDDINGS_ENABLED=false

• EMBEDDING_PROVIDER=openai

• EMBEDDING_MODEL=text-embedding-3-small

• EMBEDDING_SQLITE_PATH=.knowledge-to-action-mcp/index.sqlite

• OPENAI_API_KEY=...

Optional planning

• PLANNING_ENABLED=false

• PLANNING_PROVIDER=openai

• PLANNING_MODEL=gpt-4.1-mini

Optional workspace inspection

• EXECUTION_ENABLED=false

• EXECUTION_CAPABILITIES=workspace.search,workspace.inspect,workspace.git_status

• EXECUTION_TIMEOUT_MS=5000

• EXECUTION_MAX_OUTPUT_BYTES=32768

Install In MCP Clients

Example stdio config:

{
  "command": "npx",
  "args": ["-y", "@tac0de/knowledge-to-action-mcp"],
  "env": {
    "OBSIDIAN_VAULT_ROOT": "/path/to/vault"
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "knowledge-to-action": {
      "command": "npx",
      "args": ["-y", "@tac0de/knowledge-to-action-mcp"],
      "env": {
        "OBSIDIAN_VAULT_ROOT": "/path/to/vault"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "knowledge-to-action": {
      "command": "npx",
      "args": ["-y", "@tac0de/knowledge-to-action-mcp"],
      "env": {
        "OBSIDIAN_VAULT_ROOT": "/path/to/vault"
      }
    }
  }
}

Security Boundary

This package is designed to be useful without turning into a local shell bomb.

• vault access is read-only

• plan generation is preview-only

• embeddings are optional and local

• repo inspection is bounded to the configured working directory

• no generic bash.exec or arbitrary command tool is exposed

Good Fit

Use this project if you want:

• Obsidian-native GraphRAG

• note-to-action workflows for agents

• structured context instead of giant markdown dumps

• repo-aware handoff without broad execution access

Not Trying To Be

• a general purpose agent runtime

• a write-enabled automation framework

• a hosted knowledge platform

• a vector database product

Compatibility

• package name: @tac0de/knowledge-to-action-mcp

• legacy CLI alias: obsidian-mcp

• Node.js 20+

Status

v2.1.1 is usable now:

• typecheck passes

• unit and integration tests pass

• npm pack dry-run passes

The project is still early, but the main workflow is already working.

License

MIT