obsidian-mcp/specs/001-obsidian-mcp-bundle/quickstart.md

# Quickstart: Obsidian MCP Bundle

**Purpose**: Validate the implementation works end-to-end

## Prerequisites

- Obsidian application installed and running
- At least one Obsidian vault configured
- Obsidian CLI accessible in PATH (`obsidian help` works)
- Node.js >= 18.0.0 installed

## Setup

1. **Install dependencies**:
   ```bash
   npm install
   ```

2. **Build the bundle**:
   ```bash
   npm run build
   ```

3. **Run tests**:
   ```bash
   npm test
   ```

4. **Create the .mcpb package**:
   ```bash
   npm run pack
   # Outputs: obsidian-mcp.mcpb
   ```

## Local Testing (Before Packaging)

### 1. Start MCP Server Manually

```bash
node dist/index.js
```

Server is now listening on stdin/stdout for JSON-RPC messages.

### 2. Send Test Messages

In a separate terminal, pipe JSON-RPC requests:

```bash
# Initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node dist/index.js

# Expected: {"jsonrpc":"2.0","id":1,"result":{...}}
```

```bash
# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node dist/index.js

# Expected: {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}
```

### 3. Test a Tool

Create a test note:

```bash
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"obsidian_create_note","arguments":{"name":"Test Note","content":"# Test\n\nThis is a test note."}}}' | OBSIDIAN_VAULT="My Vault" node dist/index.js

# Expected: {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"success\":true,...}"}]}}
```

Verify in Obsidian that "Test Note.md" was created.

## Installation in Claude Desktop

1. **Open the .mcpb file** in Claude Desktop:
   - Double-click `obsidian-mcp.mcpb`
   - Or drag and drop into Claude Desktop

2. **Configure vault**:
   - Claude Desktop will prompt for vault name
   - Enter your Obsidian vault name (e.g., "My Vault")

3. **Test in conversation**:
   ```
   User: "Create a new note called 'Meeting Notes' with the content 'Discuss Q1 goals'"
   
   Claude: [Uses obsidian_create_note tool]
   "I've created a new note called 'Meeting Notes' with that content."
   ```

4. **Verify in Obsidian**:
   - Open Obsidian
   - Check that "Meeting Notes.md" exists with correct content

## Validation Checklist

Run through these scenarios to verify functionality:

### ✅ Basic File Operations (P1)

- [ ] Create a new note: `"Create a note called Test"`
- [ ] Read a note: `"What does my Test note say?"`
- [ ] Append to a note: `"Add 'new line' to Test note"`
- [ ] Delete a note: `"Delete the Test note"`

**Expected**: All operations complete in <3 seconds

### ✅ Search & Discovery (P2)

- [ ] Search vault: `"Find all notes mentioning 'project'"`
- [ ] List backlinks: `"What notes link to my Projects note?"`
- [ ] List tags: `"What are my most used tags?"`
- [ ] Unresolved links: `"Show me broken links"`

**Expected**: Search completes in <5 seconds for vaults with <10k notes

### ✅ Tasks (P3)

- [ ] List tasks: `"Show me all my incomplete tasks"`
- [ ] Toggle task: `"Mark the first task as done"`
- [ ] Daily tasks: `"Show tasks from my daily note"`

**Expected**: Task operations complete in <3 seconds

### ✅ Properties (P3)

- [ ] Set property: `"Set the 'status' property to 'in-progress' on Test note"`
- [ ] Read property: `"What's the status property on Test note?"`
- [ ] List properties: `"What properties exist in my vault?"`

**Expected**: Property operations complete in <3 seconds

### ✅ Vault Navigation (P4)

- [ ] List files: `"How many notes do I have?"`
- [ ] Vault info: `"Tell me about my vault"`
- [ ] Recent files: `"What notes did I recently open?"`

**Expected**: Navigation queries complete in <3 seconds

### ✅ Error Handling

- [ ] Obsidian not running: Stop Obsidian, try create note
  - **Expected**: "Obsidian application is not running. Please start Obsidian and try again."
  
- [ ] Ambiguous note name: Create two notes with same name in different folders, try to read by name only
  - **Expected**: Error listing all matching paths

- [ ] File not found: `"Read a note called NonexistentNote"`
  - **Expected**: "Note 'NonexistentNote' not found."

- [ ] Invalid vault: Configure with wrong vault name
  - **Expected**: "Vault '{name}' not found. Check your vault name in MCP settings."

### ✅ Protocol Compliance

- [ ] Initialize handshake completes
- [ ] tools/list returns 95 tools
- [ ] All tool responses are valid JSON
- [ ] stderr contains logs, stdout only has JSON-RPC
- [ ] Graceful shutdown on EOF/exit

### ✅ Performance

- [ ] File operations: <3s (SC-001)
- [ ] Search operations: <5s for 10k notes (SC-002)
- [ ] No timeout errors under normal conditions

### ✅ Cross-Platform

Test on all supported platforms:
- [ ] macOS (Darwin)
- [ ] Windows (win32)
- [ ] Linux

## Common Issues & Solutions

### "Obsidian not found in PATH"

**Solution**: Add Obsidian CLI to your PATH or specify full path in manifest.json mcp_config.

```json
{
  "command": "/Applications/Obsidian.app/Contents/MacOS/obsidian",
  ...
}
```

### "Vault not found"

**Solution**: Use exact vault name as shown in Obsidian. Check with `obsidian vaults`.

### "Permission denied"

**Solution**: Ensure vault directory has read/write permissions for current user.

### "Timeout errors"

**Solution**: Check Obsidian performance. Large vaults (>10k notes) may need optimization.

## Debug Mode

Enable verbose logging:

```bash
OBSIDIAN_MCP_DEBUG=true node dist/index.js
```

Logs will be written to stderr with full request/response details (sanitized).

## Next Steps After Validation

1. **Package for distribution**: `npm run pack`
2. **Test on different vaults**: Large vaults, different structures
3. **Test all 95 tools**: Comprehensive tool validation
4. **Performance benchmarking**: Measure against success criteria
5. **Security audit**: Verify input sanitization and error messages

## Success Criteria Verification

- ✅ **SC-001**: Basic file operations < 3s
- ✅ **SC-002**: Search queries < 5s (up to 10k notes)
- ✅ **SC-003**: 100% JSON validity (validate with JSON parser)
- ✅ **SC-004**: Error messages enable self-resolution (test error scenarios)
- ✅ **SC-005**: Single-click install in Claude Desktop
- ✅ **SC-006**: 95% CLI command coverage (90 of 95 tools implemented)
- ✅ **SC-007**: AI selects correct tool on first attempt (user testing)
- ✅ **SC-008**: Works on macOS, Windows, Linux

## Quick Start Summary

```bash
# 1. Build
npm install && npm run build

# 2. Test locally
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}' | OBSIDIAN_VAULT="My Vault" node dist/index.js

# 3. Package
npm run pack

# 4. Install in Claude Desktop
# Double-click obsidian-mcp.mcpb

# 5. Validate
# Ask Claude: "Create a note called Test with content Hello"
# Check Obsidian for Test.md
```

If all validation steps pass, the implementation is ready for production use! 🎉