{"id":30805559,"url":"https://github.com/aaronsb/obsidian-semantic-mcp","last_synced_at":"2025-09-06T00:59:04.328Z","repository":{"id":300862298,"uuid":"1007402270","full_name":"aaronsb/obsidian-semantic-mcp","owner":"aaronsb","description":"A semantic MCP server for Obsidian that simplifies 20+ tools into 5 AI-optimized operations with intelligent workflow hints and state-aware suggestions.","archived":false,"fork":false,"pushed_at":"2025-07-12T02:18:47.000Z","size":189,"stargazers_count":8,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-12T04:20:05.578Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaronsb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-24T00:11:44.000Z","updated_at":"2025-07-12T02:18:50.000Z","dependencies_parsed_at":"2025-06-25T11:32:33.417Z","dependency_job_id":null,"html_url":"https://github.com/aaronsb/obsidian-semantic-mcp","commit_stats":null,"previous_names":["aaronsb/obsidian-semantic-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aaronsb/obsidian-semantic-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fobsidian-semantic-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fobsidian-semantic-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fobsidian-semantic-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fobsidian-semantic-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronsb","download_url":"https://codeload.github.com/aaronsb/obsidian-semantic-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fobsidian-semantic-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273842816,"owners_count":25177921,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-06T00:59:00.276Z","updated_at":"2025-09-06T00:59:04.313Z","avatar_url":"https://github.com/aaronsb.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Obsidian Semantic MCP Server\n\n\u003e 🎉 **Exciting News!** We've taken everything we learned from this project and created something even better! Check out the new [**Obsidian MCP Plugin**](https://github.com/aaronsb/obsidian-mcp-plugin) - a native Obsidian plugin that runs directly inside your vault with improved performance, simplified setup, and enhanced features. We encourage you to try it out!\n\n[![npm version](https://badge.fury.io/js/obsidian-semantic-mcp.svg)](https://www.npmjs.com/package/obsidian-semantic-mcp)\n\nA semantic, AI-optimized MCP server for Obsidian that consolidates 20 tools into 5 intelligent operations with contextual workflow hints.\n\n---\n\n## 🚀 Try Our New Native Plugin!\n\nThis MCP server taught us valuable lessons about AI integration with Obsidian. We've applied these insights to create the **[Obsidian MCP Plugin](https://github.com/aaronsb/obsidian-mcp-plugin)**, which offers:\n\n- **Native Integration**: Runs directly inside Obsidian (no external dependencies!)\n- **Better Performance**: Direct vault access without REST API overhead\n- **Easier Setup**: Install like any Obsidian plugin - no API keys or external servers\n- **Enhanced Features**: Full access to Obsidian's internal APIs and search capabilities\n- **Improved Reliability**: No more connection issues or timeouts\n\n👉 **[Get the Obsidian MCP Plugin](https://github.com/aaronsb/obsidian-mcp-plugin)**\n\n---\n\n\u003ca href=\"https://glama.ai/mcp/servers/@aaronsb/obsidian-semantic-mcp\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@aaronsb/obsidian-semantic-mcp/badge\" alt=\"Obsidian Semantic Server MCP server\" /\u003e\n\u003c/a\u003e\n\n## Prerequisites\n\n- [Obsidian](https://obsidian.md/) installed on your computer\n- [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) plugin installed in your Obsidian vault\n- [Claude Desktop](https://claude.ai/download) app\n\n## Installation\n\n```bash\nnpm install -g obsidian-semantic-mcp\n```\n\nOr use directly with npx (recommended):\n```bash\nnpx obsidian-semantic-mcp\n```\n\nView on npm: https://www.npmjs.com/package/obsidian-semantic-mcp\n\n## Quick Start\n\n1. **Install the Obsidian Plugin:**\n   - Open Obsidian Settings → Community Plugins\n   - Browse and search for \"Local REST API\"\n   - Install the [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) plugin by Adam Coddington\n   - Enable the plugin\n   - In the plugin settings, copy your API key (you'll need this for configuration)\n\n2. **Configure Claude Desktop:**\n   \n   The npx command is automatically used in the Claude Desktop configuration. Add this to your Claude Desktop config (usually found at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n   ```json\n   {\n     \"mcpServers\": {\n       \"obsidian\": {\n         \"command\": \"npx\",\n         \"args\": [\"-y\", \"obsidian-semantic-mcp\"],\n         \"env\": {\n           \"OBSIDIAN_API_KEY\": \"your-api-key-here\",\n           \"OBSIDIAN_API_URL\": \"https://127.0.0.1:27124\",\n           \"OBSIDIAN_VAULT_NAME\": \"your-vault-name\"\n         }\n       }\n     }\n   }\n   ```\n\n## Features\n\nThis server consolidates traditional MCP tools into an AI-optimized semantic interface that makes it easier for AI agents to understand and use Obsidian operations effectively.\n\n### Key Benefits\n\n- **Simplified Interface**: 5 semantic operations instead of 21+ individual tools\n- **Contextual Workflows**: Intelligent hints guide AI agents to the next logical action\n- **State Tracking**: Token-based system prevents invalid operations\n- **Error Recovery**: Smart recovery hints when operations fail\n- **Fuzzy Matching**: Resilient text editing that handles minor variations\n- **Fragment Retrieval**: Automatically returns relevant sections from large files to conserve tokens\n\n### Why Semantic Operations?\n\nTraditional MCP servers expose many granular tools (20+), which can overwhelm AI agents and lead to inefficient tool selection. Our semantic approach:\n\n- **Consolidates 20 tools into 5 semantic operations** based on intent\n- **Provides contextual workflow hints** to guide next actions\n- **Tracks state with tokens** (inspired by Petri nets) to prevent nonsensical suggestions\n- **Offers recovery hints** when operations fail\n\n### The 5 Semantic Operations\n\n1. **`vault`** - File and folder operations\n   - Actions: `list`, `read`, `create`, `update`, `delete`, `search`, `fragments`\n   \n2. **`edit`** - Smart content editing\n   - Actions: `window` (fuzzy match), `append`, `patch`, `at_line`, `from_buffer`\n   \n3. **`view`** - Content viewing and navigation\n   - Actions: `window` (with context), `open_in_obsidian`\n   \n4. **`workflow`** - Get guided suggestions\n   - Actions: `suggest`\n   \n5. **`system`** - System operations\n   - Actions: `info`, `commands`, `fetch_web`\n   - Note: `fetch_web` fetches and converts web content to markdown (uses only `url` parameter)\n\n### Example Usage\n\nInstead of choosing between `get_vault_file`, `get_active_file`, `read_file_content`, etc., you simply use:\n\n```json\n{\n  \"operation\": \"vault\",\n  \"action\": \"read\",\n  \"params\": {\n    \"path\": \"daily-notes/2024-01-15.md\"\n  }\n}\n```\n\nThe response includes intelligent workflow hints:\n\n```json\n{\n  \"result\": { /* file content */ },\n  \"workflow\": {\n    \"message\": \"Read file: daily-notes/2024-01-15.md\",\n    \"suggested_next\": [\n      {\n        \"description\": \"Edit this file\",\n        \"command\": \"edit(action='window', path='daily-notes/2024-01-15.md', ...)\",\n        \"reason\": \"Make changes to content\"\n      },\n      {\n        \"description\": \"Follow linked notes\",\n        \"command\": \"vault(action='read', path='{linked_file}')\",\n        \"reason\": \"Explore connected knowledge\"\n      }\n    ]\n  }\n}\n```\n\n### State-Aware Suggestions\n\nThe system tracks context tokens to provide relevant suggestions:\n\n- After reading a file with `[[links]]`, it suggests following them\n- After a failed edit, it offers buffer recovery options\n- After searching, it suggests refining or reading results\n\n### Advanced Features\n\n#### Content Buffering\nThe `window` edit action automatically buffers your new content before attempting the edit. If the edit fails or you want to refine it, you can retrieve from buffer:\n\n```json\n{\n  \"operation\": \"edit\",\n  \"action\": \"from_buffer\",\n  \"params\": {\n    \"path\": \"notes/meeting.md\"\n  }\n}\n```\n\n#### Fuzzy Window Editing\nThe semantic editor uses fuzzy matching to find and replace content:\n\n```json\n{\n  \"operation\": \"edit\",\n  \"action\": \"window\",\n  \"params\": {\n    \"path\": \"daily/2024-01-15.md\",\n    \"oldText\": \"meting notes\",  // typo will be fuzzy matched\n    \"newText\": \"meeting notes\",\n    \"fuzzyThreshold\": 0.8\n  }\n}\n```\n\n#### Smart PATCH Operations\nTarget specific document structures:\n\n```json\n{\n  \"operation\": \"edit\",\n  \"action\": \"patch\",\n  \"params\": {\n    \"path\": \"projects/todo.md\",\n    \"operation\": \"append\",\n    \"targetType\": \"heading\",\n    \"target\": \"## In Progress\",\n    \"content\": \"- [ ] New task\"\n  }\n}\n```\n\n#### Fragment Retrieval for Large Documents\nThe system automatically uses intelligent fragment retrieval when reading files, significantly reducing token consumption while maintaining relevance:\n\n```json\n{\n  \"operation\": \"vault\",\n  \"action\": \"read\",\n  \"params\": {\n    \"path\": \"large-document.md\"\n  }\n}\n```\n\nReturns relevant fragments instead of the entire file:\n```json\n{\n  \"result\": {\n    \"content\": [\n      {\n        \"id\": \"file:large-document.md:frag0\",\n        \"content\": \"Most relevant section...\",\n        \"score\": 0.95,\n        \"lineStart\": 145,\n        \"lineEnd\": 167\n      }\n    ],\n    \"fragmentMetadata\": {\n      \"totalFragments\": 5,\n      \"strategy\": \"adaptive\",\n      \"originalContentLength\": 135662\n    }\n  }\n}\n```\n\n**Fragment Search Strategies:**\n- **adaptive** - TF-IDF keyword matching (default for short queries)\n- **proximity** - Finds fragments where query terms appear close together\n- **semantic** - Chunks documents into meaningful sections\n\nYou can explicitly search for fragments across your vault:\n```json\n{\n  \"operation\": \"vault\",\n  \"action\": \"fragments\",\n  \"params\": {\n    \"query\": \"project roadmap timeline\",\n    \"maxFragments\": 10,\n    \"strategy\": \"proximity\"\n  }\n}\n```\n\nTo retrieve the full file (when needed), use:\n```json\n{\n  \"operation\": \"vault\",\n  \"action\": \"read\",\n  \"params\": {\n    \"path\": \"document.md\",\n    \"returnFullFile\": true\n  }\n}\n```\n\n### Workflow Examples\n\n#### Daily Note Workflow\n1. Create today's note → 2. Add template → 3. Link yesterday's note\n\n#### Research Workflow  \n1. Search topic → 2. Read results → 3. Create synthesis note → 4. Link sources\n\n#### Refactoring Workflow\n1. Find all mentions → 2. Update links → 3. Rename/merge notes\n\n### Configuration\n\nThe semantic workflow hints are defined in `src/config/workflows.json` and can be customized for your workflow preferences.\n\n#### Fragment Retrieval Configuration\n\nThe fragment retrieval system automatically activates when reading files to conserve tokens. You can control this behavior:\n\n- **Default behavior**: Returns up to 5 relevant fragments when reading files\n- **Full file access**: Use `returnFullFile: true` parameter to get complete content\n- **Strategy selection**: The system auto-selects based on query length, or you can specify:\n  - `adaptive` for keyword matching (1-2 word queries)\n  - `proximity` for finding related terms together (3-5 word queries)\n  - `semantic` for conceptual chunking (longer queries)\n\n### Error Recovery\n\nWhen operations fail, the semantic interface provides intelligent recovery hints:\n\n```json\n{\n  \"error\": {\n    \"code\": \"FILE_NOT_FOUND\",\n    \"message\": \"File not found: daily/2024-01-15.md\",\n    \"recovery_hints\": [\n      {\n        \"description\": \"Create this file\",\n        \"command\": \"vault(action='create', path='daily/2024-01-15.md')\"\n      },\n      {\n        \"description\": \"Search for similar files\",\n        \"command\": \"vault(action='search', query='2024-01-15')\"\n      }\n    ]\n  }\n}\n```\n\n## Environment Variables\n\nThe server automatically loads environment variables from a `.env` file if present. Variables can be set in order of precedence:\n\n1. Existing environment variables (highest priority)\n2. `.env` file in current working directory\n3. `.env` file in the server directory\n\nRequired variables:\n- `OBSIDIAN_API_KEY` - Your API key from the Local REST API plugin\n\nOptional variables:\n- `OBSIDIAN_API_URL` - API URL (default: https://localhost:27124)\n  - Supports both HTTP (port 27123) and HTTPS (port 27124)\n  - HTTPS uses self-signed certificates which are automatically accepted\n- `OBSIDIAN_VAULT_NAME` - Vault name for context\n\nExample `.env` file:\n```\nOBSIDIAN_API_KEY=your-api-key-here\nOBSIDIAN_API_URL=http://127.0.0.1:27123\nOBSIDIAN_VAULT_NAME=MyVault\n```\n\n## PATCH Operations\n\nThe PATCH operations (`patch_active_file` and `patch_vault_file`) allow sophisticated content manipulation:\n\n- **Target Types:**\n  - `heading`: Target content under specific headings using paths like \"Heading 1::Subheading\"\n  - `block`: Target specific block references\n  - `frontmatter`: Target frontmatter fields\n\n- **Operations:**\n  - `append`: Add content after the target\n  - `prepend`: Add content before the target\n  - `replace`: Replace the target content\n\nExample: Append content under a specific heading:\n```json\n{\n  \"operation\": \"append\",\n  \"targetType\": \"heading\",\n  \"target\": \"Daily Notes::Today\",\n  \"content\": \"- New task added\"\n}\n```\n\n## Development\n\n```bash\n# Clone and install\ngit clone https://github.com/aaronsb/obsidian-semantic-mcp.git\ncd obsidian-semantic-mcp\nnpm install\n\n# Development mode\nnpm run dev\n\n# Testing\nnpm test              # Run all tests\nnpm run test:coverage # With coverage report\n\n# Build\nnpm run build         # Build the server\nnpm run build:full    # Test + Build\n\n# Start\nnpm start             # Start the server\n```\n\n### Architecture\n\nThe semantic system consists of:\n\n- **Semantic Router** (`src/semantic/router.ts`) - Routes operations to handlers\n- **State Tokens** (`src/semantic/state-tokens.ts`) - Tracks context state\n- **Workflow Config** (`src/config/workflows.json`) - Defines hints and suggestions\n- **Core Utilities** (`src/utils/`) - Shared functionality like file reading and fuzzy matching\n\n### Testing\n\nThe project includes comprehensive Jest tests for the semantic system:\n\n```bash\nnpm test                    # Run all tests\nnpm test semantic-router    # Test routing logic\nnpm test semantic-tools     # Test integration\n```\n\n## Known Issues\n\n- **Search functionality**: The search operation may occasionally timeout on large vaults due to API limitations in the Obsidian Local REST API plugin.\n\n## Contributing\n\nContributions are welcome! Areas of interest:\n\n- Additional workflow patterns in `workflows.json`\n- New semantic operations\n- Enhanced state tracking\n- Integration with Obsidian plugins\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fobsidian-semantic-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronsb%2Fobsidian-semantic-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fobsidian-semantic-mcp/lists"}