{"_id":"@comfucios/second-brain-mcp","_rev":"2-a2781b0600c5b1619bf7548d56a065d6","name":"@comfucios/second-brain-mcp","dist-tags":{"latest":"0.2.1"},"versions":{"0.2.0":{"name":"@comfucios/second-brain-mcp","version":"0.2.0","keywords":["mcp","obsidian","second-brain","knowledge-management","ai","openai","claude","vscode","copilot","cursor"],"author":{"name":"Ioannis Karasavvaidis","email":"ioannis@studio110.eu"},"license":"ISC","_id":"@comfucios/second-brain-mcp@0.2.0","maintainers":[{"name":"comfucios","email":"jkarasavvaidis@gmail.com"}],"homepage":"https://github.com/CoMfUcIoS/second-brain-mcp#readme","bugs":{"url":"https://github.com/CoMfUcIoS/second-brain-mcp/issues"},"bin":{"second-brain-mcp":"dist/index.js"},"dist":{"shasum":"fd2ca66819a7658dfd9c788217564a097dfd7b43","tarball":"https://registry.npmjs.org/@comfucios/second-brain-mcp/-/second-brain-mcp-0.2.0.tgz","fileCount":37,"integrity":"sha512-nOr0/JuaIoaCKUbCHdvRQvKVI6StuIWM7WD2PgVrXQa1x3DrrX7Ql25x7xKlg/x3xrHVsavzQ6VfQf+xtZU0IQ==","signatures":[{"sig":"MEUCIFHHXrUTmyYE+xtQlHZYsxt4Eb5LKpuHTt3YwayoLQLBAiEArMT4rqJi4iW/m14XH3OWwnwmreUmOButfxzn6HE+PqY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@comfucios%2fsecond-brain-mcp@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":201045},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22.12"},"gitHead":"fb97abe2da711eebbee243f7e724ae6b70be9660","scripts":{"lint":"eslint src/**/*.ts","test":"node --experimental-vm-modules node_modules/jest/bin/jest.js","build":"tsc","start":"node dist/index.js","watch":"tsc --watch","lint:fix":"eslint src/**/*.ts --fix","test:watch":"node --experimental-vm-modules node_modules/jest/bin/jest.js --watch","test:coverage":"node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"comfucios","email":"jkarasavvaidis@gmail.com"},"repository":{"url":"git+https://github.com/CoMfUcIoS/second-brain-mcp.git"},"_npmVersion":"11.11.0","description":"MCP server for any Markdown vault as a second brain (Obsidian, Foam, Logseq, plain files)","directories":{},"_nodeVersion":"24.14.1","dependencies":{"glob":"^13.0.6","fuse.js":"^7.0.0","gray-matter":"^4.0.3","better-sqlite3":"^12.4.1","@types/better-sqlite3":"^7.6.13","@modelcontextprotocol/sdk":"^1.0.4"},"_hasShrinkwrap":false,"packageManager":"npm@11.0.0","devDependencies":{"jest":"^30.2.0","eslint":"^10.3.0","ts-jest":"^29.1.1","@eslint/js":"^10.0.1","typescript":"^5.7.2","@types/jest":"^30.0.0","@types/node":"^25.3.5","@typescript-eslint/parser":"^8.45.0","@typescript-eslint/eslint-plugin":"^8.45.0"},"_npmOperationalInternal":{"tmp":"tmp/second-brain-mcp_0.2.0_1777680163361_0.1579749607315204","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@comfucios/second-brain-mcp","version":"0.2.1","description":"MCP server for any Markdown vault as a second brain (Obsidian, Foam, Logseq, plain files)","main":"dist/index.js","author":{"name":"Ioannis Karasavvaidis","email":"ioannis@studio110.eu"},"license":"ISC","type":"module","repository":{"url":"git+https://github.com/CoMfUcIoS/second-brain-mcp.git"},"bugs":{"url":"https://github.com/CoMfUcIoS/second-brain-mcp/issues"},"homepage":"https://github.com/CoMfUcIoS/second-brain-mcp#readme","bin":{"second-brain-mcp":"dist/index.js"},"scripts":{"build":"tsc","watch":"tsc --watch","start":"node dist/index.js","lint":"eslint src/**/*.ts","lint:fix":"eslint src/**/*.ts --fix","test":"node --experimental-vm-modules node_modules/jest/bin/jest.js","test:watch":"node --experimental-vm-modules node_modules/jest/bin/jest.js --watch","test:coverage":"node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage","prepublishOnly":"npm run build"},"keywords":["mcp","obsidian","second-brain","knowledge-management","ai","openai","claude","vscode","copilot","cursor"],"engines":{"node":">=22.12"},"packageManager":"npm@11.0.0","dependencies":{"@modelcontextprotocol/sdk":"^1.0.4","@types/better-sqlite3":"^7.6.13","better-sqlite3":"^12.4.1","fuse.js":"^7.0.0","glob":"^13.0.6","gray-matter":"^4.0.3"},"devDependencies":{"@eslint/js":"^10.0.1","@types/jest":"^30.0.0","@types/node":"^25.3.5","@typescript-eslint/eslint-plugin":"^8.45.0","@typescript-eslint/parser":"^8.45.0","eslint":"^10.3.0","jest":"^30.2.0","ts-jest":"^29.1.1","typescript":"^5.7.2"},"gitHead":"94b7f8c9cc4228707eb9d18931aa388edf1bcc3d","types":"./dist/index.d.ts","_id":"@comfucios/second-brain-mcp@0.2.1","_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-DavtMbuxN7obmUik/ufZ9gXud4hG/ibiDUb9QG2WQIi30QwMgJXzf0m6dhNFYKdZoUsLmByd3WvmYfnJ5DWc+A==","shasum":"5e4762a7793331d4e8323d06e98bc280c97c4d2d","tarball":"https://registry.npmjs.org/@comfucios/second-brain-mcp/-/second-brain-mcp-0.2.1.tgz","fileCount":37,"unpackedSize":201045,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@comfucios%2fsecond-brain-mcp@0.2.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFQLyEzh+nU5j8IXzxf5uj+8aChPtFnsJ5+AHnZd4aahAiEAitwScdDeI/uWfQOCIRESqi5raesYq28BL1YZDTOx1jY="}]},"_npmUser":{"name":"comfucios","email":"jkarasavvaidis@gmail.com"},"directories":{},"maintainers":[{"name":"comfucios","email":"jkarasavvaidis@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/second-brain-mcp_0.2.1_1777982527800_0.9986076504618251"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-02T00:02:43.269Z","modified":"2026-05-05T12:02:08.245Z","0.2.0":"2026-05-02T00:02:43.529Z","0.2.1":"2026-05-05T12:02:07.961Z"},"bugs":{"url":"https://github.com/CoMfUcIoS/second-brain-mcp/issues"},"author":{"name":"Ioannis Karasavvaidis","email":"ioannis@studio110.eu"},"license":"ISC","homepage":"https://github.com/CoMfUcIoS/second-brain-mcp#readme","keywords":["mcp","obsidian","second-brain","knowledge-management","ai","openai","claude","vscode","copilot","cursor"],"repository":{"url":"git+https://github.com/CoMfUcIoS/second-brain-mcp.git"},"description":"MCP server for any Markdown vault as a second brain (Obsidian, Foam, Logseq, plain files)","maintainers":[{"name":"comfucios","email":"jkarasavvaidis@gmail.com"}],"readme":"# Second Brain MCP Server\n\nA read-only MCP server for intelligent, secure access to your Obsidian vault—enabling semantic search, metadata filtering, and more for LLMs.\n\n## Features\n\n- **Efficient Database Storage**: SQLite-based indexing for large vaults with persistent caching\n- **Memory Mode Option**: Optional in-memory indexing for small vaults or development\n- **Semantic Search**: Full-text search across all notes with fuzzy matching\n- **Tag-Based Filtering**: Search by hierarchical tags (e.g., `work/puppet`, `tech/golang`)\n- **Path-Based Filtering**: Filter by directory patterns (e.g., `Work/Puppet/**`)\n- **Temporal Queries**: Filter notes by creation/modification dates\n- **Metadata Filtering**: Filter by type, status, and category\n- **Note Retrieval**: Get full content of specific notes\n- **Smart Summarization**: Generate summaries of note collections\n- **Recent Notes**: Quick access to recently modified notes\n- **Archive Control**: Optionally include archived notes in searches\n- **Knowledge Gaps**: Detect orphaned wikilinks and open questions across the vault\n- **Spaced Review**: Surface stale notes ranked by link importance for periodic review\n- **Related Notes**: Score-based discovery of related notes via shared links, tags, and title overlap\n- **Vault Graph**: Full link graph with hub detection, broken link stats, and orphan analysis\n- **Security**: Path traversal protection, file size limits, input validation\n\n## Vault Compatibility\n\nThis server works with **any directory of Markdown files** — not just Obsidian vaults. It operates purely on the filesystem and has no dependency on the Obsidian app.\n\n| Tool                                      | Compatible | Notes                                                        |\n| ----------------------------------------- | ---------- | ------------------------------------------------------------ |\n| [Obsidian](https://obsidian.md)           | ✅         | Primary use case                                             |\n| [Foam](https://foambubble.github.io/foam) | ✅         | Confirmed — same `.md` + `[[wikilinks]]` format              |\n| [Logseq](https://logseq.com)              | ✅         | Plain `.md` files work; Logseq-specific block syntax ignored |\n| [Dendron](https://www.dendron.so)         | ✅         | Hierarchical filenames index correctly                       |\n| Plain Markdown directories                | ✅         | No frontmatter required — defaults applied                   |\n\n### Using with Foam\n\nPoint `--vault-path` at your Foam workspace root. No configuration changes needed:\n\n```bash\nnpx -y @comfucios/second-brain-mcp --vault-path \"/path/to/your/foam-workspace\"\n```\n\nFoam features that work out of the box:\n\n- `[[wikilinks]]` and `[[target|aliased links]]` resolved in graph tools\n- YAML frontmatter tags (both inline `[tag1, tag2]` and block list style)\n- Nested tag hierarchies (`work/backend`)\n- Sub-folder structure (`notes/`, `journal/`, `projects/`)\n- Notes without frontmatter indexed with safe defaults\n\nThe `.vscode/` folder is automatically excluded from indexing.\n\n## Read-Only Design\n\nThis MCP server is intentionally **read-only** to ensure your vault remains safe during AI interactions. It provides:\n\n- ✅ Search and retrieve notes\n- ✅ Filter by metadata and paths\n- ✅ Generate summaries and statistics\n- ❌ No note creation or editing\n- ❌ No file modifications\n\nFor write operations, consider using dedicated Obsidian plugins with built-in safety checks.\n\n## Installation\n\n## Configuration & Installation\n\n### One-Click Installation\n\n- **VS Code:**\n  [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Second_Brain_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=second-brain-mcp&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40comfucios%2Fsecond-brain-mcp%22%5D%7D)\n- **VS Code Insiders:**\n  [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Second_Brain_MCP-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=second-brain-mcp&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40comfucios%2Fsecond-brain-mcp%22%5D%7D)\n- **Cursor:**\n  [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_Second_Brain_MCP-00D8FF?style=flat-square&logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=second-brain-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IC15IEBjb21mdWNpb3Mvc2Vjb25kLWJyYWluLW1jcCIsImVudiI6e319)\n\n### Manual Installation\n\nNo installation needed! Use directly with npx:\n\n```bash\nnpx -y @comfucios/second-brain-mcp --vault-path \"/path/to/your/vault\"\n```\n\n#### Local Development\n\n```bash\ncd second-brain-mcp\nnpm install\nnpm run build\nnpm link\n```\n\nThis makes the server available globally as `second-brain-mcp`.\n\n### Claude Code & Claude Desktop\n\n#### Claude Code\n\nAdd the server using:\n\n```bash\nclaude mcp add second-brain -- npx -y @comfucios/second-brain-mcp --vault-path \"/path/to/your/vault\"\n```\n\n#### Claude Desktop\n\nAdd to your Claude Desktop configuration file:\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  \n**Windows:** `%APPDATA%/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"second-brain\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@comfucios/second-brain-mcp\",\n        \"--vault-path\",\n        \"/path/to/your/vault\"\n      ]\n    }\n  }\n}\n```\n\nSee [docs/configuration.md](docs/configuration.md) for vault structure, CLI arguments, and configuration examples.\n\nSee [docs/api.md](docs/api.md) for the full MCP API reference and usage examples.\n\n## Usage with Claude Code\n\nAdd to your MCP configuration file.\n\n### Single Vault Configuration\n\n**macOS/Linux:** Edit `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows:** Edit `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"second-brain\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@comfucios/second-brain-mcp\",\n        \"--vault-path\",\n        \"/Users/ioanniskarasavvaidis/Documents/Obsidian Vault\"\n      ]\n    }\n  }\n}\n```\n\n### Multiple Vault Configuration\n\nYou can configure multiple vault instances:\n\n```json\n{\n  \"mcpServers\": {\n    \"second-brain-personal\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@comfucios/second-brain-mcp\",\n        \"--vault-path\",\n        \"/Users/username/Documents/Personal Vault\"\n      ]\n    },\n    \"second-brain-work\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@comfucios/second-brain-mcp\",\n        \"--vault-path\",\n        \"/Users/username/Documents/Work Vault\"\n      ]\n    }\n  }\n}\n```\n\n### Local Development Setup\n\nIf you're developing locally with `npm link`:\n\n```json\n{\n  \"mcpServers\": {\n    \"second-brain\": {\n      \"command\": \"second-brain-mcp\",\n      \"args\": [\"--vault-path\", \"/path/to/your/vault\"]\n    }\n  }\n}\n```\n\nSee [docs/examples.md](docs/examples.md) for more example queries.\n\n## Documentation\n\nSee [docs/README.md](docs/README.md) for:\n\n- API Reference\n- Configuration & CLI Options\n- Example Queries\n- Development & Storage Architecture\n- Contributing\n- Dependencies\n- Architecture & Database Schema\n- Security & Search\n- Example Queries\n- Development\n- Contributing\n- Dependencies\n- [License](#license)\n\n## Quick Start\n\nRun the server instantly with npx (no install required):\n\n```bash\nnpx -y @comfucios/second-brain-mcp --vault-path \"/path/to/your/vault\"\n```\n\nOr add to Claude Code/Claude Desktop (see Configuration & Installation below).\n\n---\n\n## Troubleshooting & FAQ\n\nSee [docs/configuration.md](docs/configuration.md#troubleshooting--faq) for common issues and solutions.\n\nSee [docs/search.md](docs/search.md) for details on search weights and scoring.\n\nSee [docs/security.md](docs/security.md) for details on security features and protections.\n\nSee [docs/development.md](docs/development.md) for development workflow and storage details.\n\nSee [docs/contributing.md](docs/contributing.md) for contribution guidelines.\n\n## Storage Architecture\n\nThe server uses **SQLite database storage by default** for efficient indexing and persistent caching:\n\n- **Database Mode (Default)**: Stores indexed notes in `.second-brain-mcp/notes.db` within your vault\n  - Persistent indexing (survives server restarts)\n  - Efficient for large vaults (1000+ notes)\n  - Full-text search with SQLite FTS5\n  - Lower memory usage\n\n- **Memory Mode (Optional)**: Use `--use-memory` flag for in-memory storage\n  - Faster for small vaults (<100 notes)\n  - No disk I/O overhead\n  - Useful for development and testing\n  - Uses Fuse.js for fuzzy search\n\nSee [docs/architecture.md](docs/architecture.md) for the architecture diagram.\nSee [docs/database-schema.md](docs/database-schema.md) for the database schema.\n\n## Architecture\n\n- **`src/index.ts`**: MCP server implementation with tool handlers\n- **`src/vault.ts`**: Vault indexing orchestration and security controls\n- **`src/storage.ts`**: Storage interface abstraction\n- **`src/database-storage.ts`**: SQLite-based storage implementation\n- **`src/memory-storage.ts`**: In-memory storage implementation with Fuse.js\n- **`src/storage-factory.ts`**: Storage factory pattern for mode selection\n- **`src/config.ts`**: Configuration management with defaults\n- **`src/types.ts`**: TypeScript type definitions and validation utilities\n- **`src/__tests__/`**: Unit tests for critical functionality\n\nSee [docs/dependencies.md](docs/dependencies.md) for a full list of production and development dependencies.\n\n---\n\n## Support\n\nIf second-brain-mcp saves you time, consider [sponsoring me on GitHub](https://github.com/sponsors/comfucios) or [buy me a coffee](https://www.buymeacoffee.com/comfucios).\n\n## License\n\nMIT\n","readmeFilename":"README.md"}