# arosentiehl24/a2rg.obsidianmcp architecture

> Architecture diagram of the GitHub repository arosentiehl24/a2rg.obsidianmcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arosentiehl24/a2rg.obsidianmcp
- Repository: https://github.com/arosentiehl24/a2rg.obsidianmcp

## Overview

A2RG MCP Bridge exposes Obsidian vault operations to MCP clients through a localhost plugin bridge, with an optional stdio client that prefers REST and falls back to local filesystem access. The plugin path is wired by the Obsidian plugin entry point; the stdio path uses its own MCP registry and hybrid router. Search, linked-note graph traversal, path validation, TLS, and persistent search caching are meaningful supporting capabilities. Edges reflect README statements and shown calls or imports; several unsampled modules are represented by their exact tree paths, with uncertain wiring omitted.

Main entry points: [`src/index.ts`](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/index.ts) (Stdio MCP Runtime), [`plugin/src/adapters/obsidian-vault-adapter.ts`](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/adapters/obsidian-vault-adapter.ts) (Obsidian Adapter), [`src/vault.ts`](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/vault.ts) (Filesystem Vault), [`plugin/src/main.ts`](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/main.ts) (Plugin Lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugin["Obsidian Plugin"]
  node_plugin_main["Plugin Lifecycle<br/>[main.ts]"]
  node_settings["Bridge Settings<br/>[settings.ts]"]
  node_tls["Local TLS"]
  node_http_bridge["HTTP MCP Bridge<br/>[http-bridge.ts]"]
end

subgraph group_stdio["Stdio Fallback"]
  node_stdio_runtime["Stdio MCP Runtime<br/>[index.ts]"]
  node_config["Runtime Config<br/>[config.ts]"]
  node_stdio_registry["Tool Dispatch"]
  node_router["Hybrid Router<br/>[router.ts]"]
  node_api_client["Plugin REST Client<br/>[api.ts]"]
  node_http_transport["HTTP Transport<br/>[http-transport.ts]"]
end

subgraph group_vault["Vault Services"]
  node_vault_adapter["Obsidian Adapter"]
  node_graph_service["Linked Note Graph"]
  node_vault_port["Vault Port<br/>[vault-port.ts]"]
  node_filesystem_vault["Filesystem Vault<br/>[vault.ts]"]
  node_path_resolver["Vault Path Resolver"]
end

subgraph group_shared["Shared Search"]
  node_tool_registry["MCP Tool Registry"]
  node_search_service["Obsidian Search"]
  node_search_index["BM25 Search Index<br/>[search-index.ts]"]
  node_search_cache[("Persistent Search Cache")]
  node_tool_schemas["Tool Schemas<br/>[tool-schemas.ts]"]
end

node_mcp_client(("MCP Client"))
node_obsidian_app["Obsidian Vault APIs"]
node_stdio_client(("Stdio MCP Client"))

node_mcp_client -->|"calls MCP"| node_http_bridge
node_plugin_main -->|"starts bridge"| node_http_bridge
node_plugin_main -->|"constructs adapter"| node_vault_adapter
node_plugin_main -->|"loads settings"| node_settings
node_plugin_main -->|"loads TLS"| node_tls
node_http_bridge -->|"uses tools"| node_tool_registry
node_http_bridge -->|"dispatches vault calls"| node_vault_adapter
node_vault_adapter -->|"reads and writes"| node_obsidian_app
node_vault_adapter -->|"delegates search"| node_search_service
node_vault_adapter -->|"delegates graph"| node_graph_service
node_vault_adapter -->|"uses path rules"| node_vault_port
node_search_service -->|"ranks queries"| node_search_index
node_stdio_client -->|"starts stdio"| node_stdio_runtime
node_stdio_runtime -->|"loads configuration"| node_config
node_stdio_runtime -->|"dispatches tools"| node_stdio_registry
node_stdio_runtime -->|"constructs router"| node_router
node_stdio_runtime -->|"constructs client"| node_api_client
node_stdio_runtime -->|"constructs vault"| node_filesystem_vault
node_stdio_registry -->|"routes tool calls"| node_router
node_stdio_registry -->|"validates arguments"| node_tool_schemas
node_router -->|"tries REST first"| node_api_client
node_router -->|"falls back to files"| node_filesystem_vault
node_api_client -->|"sends requests"| node_http_transport
node_filesystem_vault -->|"resolves paths"| node_path_resolver
node_filesystem_vault -->|"indexes and searches"| node_search_index
node_filesystem_vault -->|"persists index"| node_search_cache
node_stdio_runtime -.->|"serves tools"| node_mcp_client

click node_plugin_main "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/main.ts"
click node_settings "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/settings.ts"
click node_tls "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/tls/local-certificate.ts"
click node_http_bridge "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/bridge/http-bridge.ts"
click node_tool_registry "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/mcp-tool-registry.ts"
click node_vault_adapter "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/adapters/obsidian-vault-adapter.ts"
click node_search_service "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/services/obsidian-search-service.ts"
click node_graph_service "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/services/obsidian-graph-service.ts"
click node_vault_port "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/ports/vault-port.ts"
click node_stdio_runtime "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/index.ts"
click node_config "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/config.ts"
click node_stdio_registry "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/mcp-tool-registry.ts"
click node_router "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/router.ts"
click node_api_client "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/api.ts"
click node_http_transport "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/http-transport.ts"
click node_filesystem_vault "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/vault.ts"
click node_path_resolver "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/vault-path-resolver.ts"
click node_search_index "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/search-index.ts"
click node_search_cache "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/persistent-search-cache.ts"
click node_tool_schemas "https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/tool-schemas.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin_main,node_settings,node_tls,node_http_bridge,node_mcp_client,node_stdio_client toneBlue
class node_stdio_runtime,node_config,node_stdio_registry,node_router,node_api_client,node_http_transport toneAmber
class node_vault_adapter,node_graph_service,node_vault_port,node_filesystem_vault,node_path_resolver,node_obsidian_app toneMint
class node_tool_registry,node_search_service,node_search_index,node_search_cache,node_tool_schemas toneRose
```

## Components

### Obsidian Plugin

- [Plugin Lifecycle](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/main.ts): `plugin/src/main.ts`
- [Bridge Settings](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/settings.ts): `plugin/src/settings.ts`
- [Local TLS](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/tls/local-certificate.ts): `plugin/src/tls/local-certificate.ts`
- [HTTP MCP Bridge](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/bridge/http-bridge.ts): `plugin/src/bridge/http-bridge.ts`

### Stdio Fallback

- [Stdio MCP Runtime](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/index.ts): `src/index.ts`
- [Runtime Config](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/config.ts): `src/config.ts`
- [Tool Dispatch](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/mcp-tool-registry.ts): `src/mcp-tool-registry.ts`
- [Hybrid Router](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/router.ts): `src/router.ts`
- [Plugin REST Client](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/api.ts): `src/api.ts`
- [HTTP Transport](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/http-transport.ts): `src/http-transport.ts`

### Vault Services

- [Obsidian Adapter](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/adapters/obsidian-vault-adapter.ts): `plugin/src/adapters/obsidian-vault-adapter.ts`
- [Linked Note Graph](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/services/obsidian-graph-service.ts): `plugin/src/services/obsidian-graph-service.ts`
- [Vault Port](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/ports/vault-port.ts): `plugin/src/ports/vault-port.ts`
- [Filesystem Vault](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/vault.ts): `src/vault.ts`
- [Vault Path Resolver](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/vault-path-resolver.ts): `src/vault-path-resolver.ts`

### Shared Search

- [MCP Tool Registry](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/mcp-tool-registry.ts): `src/mcp-tool-registry.ts`
- [Obsidian Search](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/plugin/src/services/obsidian-search-service.ts): `plugin/src/services/obsidian-search-service.ts`
- [BM25 Search Index](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/search-index.ts): `src/search-index.ts`
- [Persistent Search Cache](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/persistent-search-cache.ts): `src/persistent-search-cache.ts`
- [Tool Schemas](https://github.com/arosentiehl24/a2rg.obsidianmcp/blob/master/src/tool-schemas.ts): `src/tool-schemas.ts`

### Other components

- **MCP Client**
- **Obsidian Vault APIs**
- **Stdio MCP Client**

## Connections

- MCP Client → HTTP MCP Bridge: calls MCP (evidence: `README.md`)
- Plugin Lifecycle → HTTP MCP Bridge: starts bridge (evidence: `plugin/src/main.ts`)
- Plugin Lifecycle → Obsidian Adapter: constructs adapter (evidence: `plugin/src/main.ts`)
- Plugin Lifecycle → Bridge Settings: loads settings (evidence: `plugin/src/main.ts`)
- Plugin Lifecycle → Local TLS: loads TLS (evidence: `plugin/src/main.ts`)
- HTTP MCP Bridge → MCP Tool Registry: uses tools (evidence: `plugin/src/bridge/http-bridge.ts`)
- HTTP MCP Bridge → Obsidian Adapter: dispatches vault calls (evidence: `plugin/src/bridge/http-bridge.ts`)
- Obsidian Adapter → Obsidian Vault APIs: reads and writes (evidence: `plugin/src/adapters/obsidian-vault-adapter.ts`)
- Obsidian Adapter → Obsidian Search: delegates search (evidence: `plugin/src/adapters/obsidian-vault-adapter.ts`)
- Obsidian Adapter → Linked Note Graph: delegates graph (evidence: `plugin/src/adapters/obsidian-vault-adapter.ts`)
- Obsidian Adapter → Vault Port: uses path rules (evidence: `plugin/src/adapters/obsidian-vault-adapter.ts`)
- Obsidian Search → BM25 Search Index: ranks queries (evidence: `plugin/src/services/obsidian-search-service.ts`)
- Stdio MCP Client → Stdio MCP Runtime: starts stdio (evidence: `README.md`)
- Stdio MCP Runtime → Runtime Config: loads configuration (evidence: `src/index.ts`)
- Stdio MCP Runtime → Tool Dispatch: dispatches tools (evidence: `src/index.ts`)
- Stdio MCP Runtime → Hybrid Router: constructs router (evidence: `src/index.ts`)
- Stdio MCP Runtime → Plugin REST Client: constructs client (evidence: `src/index.ts`)
- Stdio MCP Runtime → Filesystem Vault: constructs vault (evidence: `src/index.ts`)
- Tool Dispatch → Hybrid Router: routes tool calls (evidence: `src/mcp-tool-registry.ts`)
- Tool Dispatch → Tool Schemas: validates arguments (evidence: `src/mcp-tool-registry.ts`)
- Hybrid Router → Plugin REST Client: tries REST first (evidence: `src/router.ts`)
- Hybrid Router → Filesystem Vault: falls back to files (evidence: `src/router.ts`)
- Plugin REST Client → HTTP Transport: sends requests (evidence: `src/api.ts`)
- Filesystem Vault → Vault Path Resolver: resolves paths (evidence: `src/vault.ts`)
- Filesystem Vault → BM25 Search Index: indexes and searches (evidence: `src/vault.ts`)
- Filesystem Vault → Persistent Search Cache: persists index (evidence: `src/vault.ts`)
- Stdio MCP Runtime → MCP Client: serves tools (evidence: `README.md`)