Vault MCP Server

A Model Context Protocol (MCP) server for interacting with the UniHub Vault - a file-based issue tracking and knowledge management system.

Quick Start

Prerequisites

• Python 3.12+
• uv package manager

Installation

uv sync

Running the Server

uv run python main.py

Configuration

Set the VAULT_PATH environment variable to point to your UniHub Vault directory:

export VAULT_PATH=/path/to/your/vault

Default locations (checked automatically if VAULT_PATH not set):

• ./.unihub-vault/UniHubVault (relative to project root)
• ~/Q/massage.kg/.unihub-vault/UniHubVault

---

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "vault": {
      "command": "uv",
      "args": ["run", "python", "/absolute/path/to/vault-mcp-server/main.py"],
      "env": {
        "VAULT_PATH": "/home/lexx/Q/massage.kg/.unihub-vault/UniHubVault"
      }
    }
  }
}

Cursor IDE

Add to .cursor/mcp.json in your workspace:

{
  "mcpServers": {
    "vault": {
      "command": "uv",
      "args": ["run", "python", "${workspaceFolder}/main.py"],
      "env": {
        "VAULT_PATH": "/home/lexx/Q/massage.kg/.unihub-vault/UniHubVault"
      }
    }
  }
}

Windsurf / Codeium

Add to your MCP settings:

{
  "vault": {
    "command": "uv",
    "args": ["run", "python", "/absolute/path/to/vault-mcp-server/main.py"],
    "env": {
      "VAULT_PATH": "/path/to/vault"
    }
  }
}

Generic MCP Client

{
  "vault": {
    "command": "python",
    "args": ["/absolute/path/to/vault-mcp-server/main.py"],
    "env": {
      "VAULT_PATH": "/path/to/vault"
    }
  }
}

---

Available Tools

Issue Management (5 tools)

Tool	Description
create_issue(name, body, tags?)	Create issue in 10_Inbox, returns 8-char ID
read_issue(iss_uniq_id)	Read issue content by unique ID
update_issue(iss_uniq_id, content, append?)	Update or append to issue
move_issue(iss_uniq_id, stage)	Move issue to stage (10_Inbox, 20_Processing, 30_ToReview, 999_Finished)
list_issues(stage?)	List issues in stage (default: 10_Inbox)

Vault Operations (3 tools)

Tool	Description
read_note(path)	Read any note from vault (path relative to vault root)
list_notes(directory?)	List markdown files in directory
search_vault(query)	Search all .md files (auto-detects regex vs keyword)

Status (1 tool)

Tool	Description
get_status()	Dashboard: issues by stage + recently modified notes

Telegram (3 tools)

Tool	Description
set_telegram_webhook(url)	Set bot webhook URL
check_telegram_webhook()	Check webhook status
poll_telegram_updates()	Poll and forward updates to local webhook

---

Issue Lifecycle

10_Inbox → 20_Processing → 30_ToReview → 999_Finished
   ↑            ↑              ↑
 create      move           move

Typical Workflow

1. create_issue("Bug in login", "Users can't login with SSO", ["bug", "auth"])
   → Returns: "a1b2c3d4"

2. list_issues("10_Inbox")
   → Shows new issue in inbox

3. read_issue("a1b2c3d4")
   → Returns full issue content

4. move_issue("a1b2c3d4", "20_Processing")
   → Moves to processing stage

5. update_issue("a1b2c3d4", "\n## Investigation\nChecked logs...", append=True)
   → Appends investigation notes

6. move_issue("a1b2c3d4", "30_ToReview")
   → Moves to review when done

7. get_status()
   → Shows overview of all stages

Stage Names

Both full and short names are supported:

Short	Full
inbox	10_Inbox
processing	20_Processing
review	30_ToReview
finished	999_Finished

---

Tool Examples

Create and Track an Issue

create_issue(name="Add dark mode", body="Users requested dark theme", tags=["feature", "ui"])
→ "f5e4d3c2"

read_issue("f5e4d3c2")
→ Full issue content

update_issue("f5e4d3c2", "\n## Notes\nPriority: high", append=True)
→ "Successfully appended to issue f5e4d3c2"

move_issue("f5e4d3c2", "processing")
→ "Moved issue f5e4d3c2 to 20_Processing"

Search and Read Notes

search_vault("authentication")
→ 50_Protocols/Auth.md:5: ## Authentication Flow
  20_Processing/<~15-nov~> abc123_login.md:12: User authentication fails...

read_note("50_Protocols/Auth.md")
→ Full protocol content

list_notes("50_Protocols")
→ Auth.md
   Security.md
   ...

Get Status Overview

get_status()
→ ## Vault Status Overview

   ### Issues by Stage

   **10_Inbox**: 3 issue(s)
     - <~15-nov~> abc123_login.md
     - <~16-nov~> def456_search.md
     - <~17-nov~> ghi789_ui.md

   **20_Processing**: 1 issue(s)
     - <~10-nov~> f5e4d3c2_dark_mode.md

   **30_ToReview**: 0 issue(s)

   **999_Finished**: 12 issue(s)
     ...

   ### Recently Modified Notes

     - 20_Processing/<~10-nov~> f5e4d3c2_dark_mode.md (0d ago, 2025-03-29)
     - 50_Protocols/Auth.md (2d ago, 2025-03-27)

---

Running Tests

uv run python test_issue_tools.py

This runs an integration test covering the full issue lifecycle.

---

Architecture

• FastMCP server framework for MCP protocol handling
• File-based storage using markdown files in stage directories
• Path safety validation to prevent directory traversal
• Telegram integration via bot token from backend/.env