Bill/obsidian-mcp-server
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: remove development and setup documentation

Browse Source 
- Removed implementation summary, quickstart guide, and roadmap files to simplify documentation
- Streamlined README.md by removing development setup instructions and release process details
- Retained core plugin documentation including features, usage, and configuration
- Simplified authentication section to focus on key functionality
This commit is contained in:
Bill Ballou
2025-10-25 22:13:39 -04:00
parent 6edb380234
commit 246182191c
4 changed files with 2 additions and 2168 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
IMPLEMENTATION_SUMMARY.md
View File

@@ -1,82 +0,0 @@
# Implementation Summary: 100% Utility Coverage
**Date:** 2025-01-20
**Branch:** feature/utils-coverage
**Goal:** Achieve 100% test coverage on all utility modules using dependency injection pattern
## Achievement Summary
✅ **All objectives met**
### Coverage Improvements
| Utility | Before | After | Improvement |
|---------|--------|-------|-------------|
| glob-utils.ts | 14.03% | **100%** | +85.97% |
| frontmatter-utils.ts | 47.86% | **96.58%** | +48.72% |
| search-utils.ts | 1.78% | **100%** | +98.22% |
| link-utils.ts | 13.76% | **100%** | +86.24% |
| waypoint-utils.ts | 49.18% | **100%** | +50.82% |
**Note:** frontmatter-utils.ts at 96.58% - remaining 3.42% is unreachable defensive code (lines 253-255, 310)
### Test Metrics
**Before:**
- Total tests: 202
- Utility tests: 0
- Coverage: 66.75% (overall), utilities ranged from 1.78% to 49.18%
**After:**
- Total tests: 485 (+283)
- Utility tests: 283
- Coverage: 96.64% (overall), target utilities at 100%
**Test Breakdown:**
- glob-utils.test.ts: 52 tests
- frontmatter-utils.test.ts: 82 tests
- search-utils.test.ts: 51 tests
- link-utils.test.ts: 46 tests
- waypoint-utils.test.ts: 52 tests
### Architecture Changes
**Dependency Injection Implementation:**
1. **Refactored Utilities:**
- search-utils.ts - Now accepts IVaultAdapter instead of App
- link-utils.ts - Now accepts IVaultAdapter and IMetadataCacheAdapter instead of App
- waypoint-utils.ts - Now accepts IVaultAdapter instead of App
2. **Updated VaultTools:**
- Removed App dependency from constructor
- Now only requires IVaultAdapter and IMetadataCacheAdapter
- Passes adapters to all utility method calls
- Removed duplicate helper methods (delegated to LinkUtils)
3. **Adapter Reuse:**
- Leveraged existing adapter interfaces from previous refactoring
- No new abstractions needed
- Consistent pattern across entire codebase
### Commits
1. 6730f93 - test: add comprehensive glob-utils tests (52 tests)
2. 9a753a7 - test: add comprehensive frontmatter-utils tests (82 tests)
3. c29d70f - refactor: search-utils to use IVaultAdapter
4. f114194 - refactor: link-utils to use adapters
5. 94c14b4 - refactor: waypoint-utils to use IVaultAdapter
6. d7bea8a - refactor: update VaultTools to pass adapters to utils
7. f54a8c1 - test: add comprehensive search-utils tests (51 tests)
8. 61fabbd - test: add comprehensive link-utils tests (46 tests)
9. 3720048 - test: add comprehensive waypoint-utils tests (52 tests)
### Build Status
✅ All tests passing: 485/485
✅ Build successful: No type errors
✅ Coverage goals met: 100% on target utilities
---
**Status:** ✅ COMPLETE - Ready for merge

198
QUICKSTART.md
View File

@@ -1,198 +0,0 @@
# Quick Start Guide
## 🚀 Getting Started
### 1. Enable the Plugin
1. Open Obsidian
2. Go to **Settings** → **Community Plugins**
3. Find **MCP Server** in the list
4. Toggle it **ON**
### 2. Start the Server
**Option A: Via Ribbon Icon**
- Click the server icon (📡) in the left sidebar
**Option B: Via Command Palette**
- Press `Ctrl/Cmd + P`
- Type "Start MCP Server"
- Press Enter
**Option C: Auto-start**
- Go to **Settings** → **MCP Server**
- Enable "Auto-start server"
- Server will start automatically when Obsidian launches
### 3. Verify Server is Running
Check the status bar at the bottom of Obsidian:
- **Running**: `MCP: Running (3000)`
- **Stopped**: `MCP: Stopped`
Or visit: http://127.0.0.1:3000/health
### 4. Test the Connection
Run the test client:
```bash
node test-client.js
```
Expected output:
```
🧪 Testing Obsidian MCP Server
Server: http://127.0.0.1:3000/mcp
API Key: None
1️⃣ Testing initialize...
✅ Initialize successful
Server: obsidian-mcp-server 1.0.0
Protocol: 2024-11-05
2️⃣ Testing tools/list...
✅ Tools list successful
Found 7 tools:
- read_note: Read the content of a note from the Obsidian vault
- create_note: Create a new note in the Obsidian vault
...
🎉 All tests passed!
```
## 🔧 Configuration
### Basic Settings
Go to **Settings** → **MCP Server**:
| Setting | Default | Description |
|---------|---------|-------------|
| Port | 3000 | HTTP server port |
| Auto-start | Off | Start server on Obsidian launch |
| Enable CORS | On | Allow cross-origin requests |
| Allowed Origins | * | Comma-separated list of allowed origins |
### Security Settings
| Setting | Default | Description |
|---------|---------|-------------|
| Enable Authentication | Off | Require API key for requests |
| API Key | (empty) | Bearer token for authentication |
## 🔌 Connect an MCP Client
### Claude Desktop
Edit your Claude Desktop config file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
Add:
```json
{
"mcpServers": {
"obsidian": {
"url": "http://127.0.0.1:3000/mcp"
}
}
}
```
Restart Claude Desktop.
### Other MCP Clients
Use the endpoint: `http://127.0.0.1:3000/mcp`
## 📝 Available Tools
Once connected, you can use these tools:
- **read_note** - Read note content
- **create_note** - Create a new note
- **update_note** - Update existing note
- **delete_note** - Delete a note
- **search_notes** - Search vault by query
- **list_notes** - List all notes or notes in a folder
- **get_vault_info** - Get vault metadata
## 🔒 Using Authentication
1. Enable authentication in settings
2. Set an API key (e.g., `my-secret-key-123`)
3. Include in requests:
```bash
curl -X POST http://127.0.0.1:3000/mcp \
-H "Authorization: Bearer my-secret-key-123" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
Or in Claude Desktop config:
```json
{
"mcpServers": {
"obsidian": {
"url": "http://127.0.0.1:3000/mcp",
"headers": {
"Authorization": "Bearer my-secret-key-123"
}
}
}
}
```
## ❓ Troubleshooting
### Server won't start
**Error: Port already in use**
- Change the port in settings
- Or stop the process using port 3000
**Error: Cannot find module**
- Run `npm install` in the plugin directory
- Rebuild with `npm run build`
### Cannot connect from client
**Check server is running**
- Look at status bar: should show "MCP: Running (3000)"
- Visit http://127.0.0.1:3000/health
**Check firewall**
- Ensure localhost connections are allowed
- Server only binds to 127.0.0.1 (localhost)
**Check authentication**
- If enabled, ensure API key is correct
- Check Authorization header format
### Tools not working
**Path errors**
- Use relative paths from vault root
- Example: `folder/note.md` not `/full/path/to/note.md`
**Permission errors**
- Ensure Obsidian has file system access
- Check vault is not read-only
## 🎯 Next Steps
- Read the full [README.md](README.md) for detailed documentation
- Explore the [MCP Protocol Documentation](https://modelcontextprotocol.io)
- Check example requests in the README
- Customize settings for your workflow
## 💡 Tips
- Use the ribbon icon for quick server toggle
- Enable auto-start for seamless integration
- Use authentication for additional security
- Monitor the status bar for server state
- Check Obsidian console (Ctrl+Shift+I) for detailed logs

47
README.md
View File

@@ -74,7 +74,7 @@ An Obsidian plugin that makes your vault accessible via the [Model Context Proto
### Authentication
Authentication is **mandatory** and cannot be disabled. An API key is automatically generated when you first install the plugin and is encrypted using your system's secure credential storage (macOS Keychain, Windows Credential Manager, Linux Secret Service where available).
An API key is automatically generated when you first install the plugin and is encrypted using your system's secure credential storage (macOS Keychain, Windows Credential Manager, Linux Secret Service where available).
## Usage
@@ -212,45 +212,6 @@ npm run build # Production build
- Enable plugin in settings window.
- For updates to the Obsidian API run `npm update` in the command line under your repo folder.
## Releasing new releases
- Update your `manifest.json` with your new version number, such as `1.0.1`, and the minimum Obsidian version required for your latest release.
- Update your `versions.json` file with `"new-plugin-version": "minimum-obsidian-version"` so older versions of Obsidian can download an older version of your plugin that's compatible.
- Create new GitHub release using your new version number as the "Tag version". Use the exact version number, don't include a prefix `v`. See here for an example: https://github.com/obsidianmd/obsidian-sample-plugin/releases
- Upload the files `manifest.json`, `main.js`, `styles.css` as binary attachments. Note: The manifest.json file must be in two places, first the root path of your repository and also in the release.
- Publish the release.
> You can simplify the version bump process by running `npm version patch`, `npm version minor` or `npm version major` after updating `minAppVersion` manually in `manifest.json`.
> The command will bump version in `manifest.json` and `package.json`, and add the entry for the new version to `versions.json`
## Adding your plugin to the community plugin list
- Check the [plugin guidelines](https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines).
- Publish an initial version.
- Make sure you have a `README.md` file in the root of your repo.
- Make a pull request at https://github.com/obsidianmd/obsidian-releases to add your plugin.
## How to use
- Clone this repo.
- Make sure your NodeJS is at least v16 (`node --version`).
- `npm i` or `yarn` to install dependencies.
- `npm run dev` to start compilation in watch mode.
## Manually installing the plugin
- Copy over `main.js`, `styles.css`, `manifest.json` to your vault `VaultFolder/.obsidian/plugins/your-plugin-id/`.
## Improve code quality with eslint (optional)
- [ESLint](https://eslint.org/) is a tool that analyzes your code to quickly find problems. You can run ESLint against your plugin to find common bugs and ways to improve your code.
- To use eslint with this project, make sure to install eslint from terminal:
- `npm install -g eslint`
- To use eslint to analyze this project use this command:
- `eslint main.ts`
- eslint will then create a report with suggestions for code improvement by file and line number.
- If your source code is in a folder, such as `src`, you can use eslint with this command to analyze all files in that folder:
- `eslint ./src/`
## Funding URL
You can include funding URLs where people who use your plugin can financially support it.
@@ -273,8 +234,4 @@ If you have multiple URLs, you can also do:
"Patreon": "https://www.patreon.com/"
}
}
```
## API Documentation
See https://github.com/obsidianmd/obsidian-api
```

1843
ROADMAP.md
View File

File diff suppressed because it is too large Load Diff