AI导哈

文件问题追踪与知识管理系统

Vault MCP Server是一个基于文件的UniHub Vault问题追踪和知识管理系统，提供问题创建、读取、更新和搜索功能，适用于开发团队和知识管理场景。

  • by deceptikon
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 deceptikon/vault-mcp-server

使用说明

保险库MCP服务器

用于与UniHub Vault交互的模型上下文协议（MCP）服务器，UniHub Vault是一个基于文件的问题跟踪和知识管理系统。

快速开始

先决条件

  • Python 3.12+
  • uv 包管理器

安装

uv sync

运行服务器

uv run python main.py

配置

设置 VAULT_PATH 指向UniHub Vault目录的环境变量：

export VAULT_PATH=/path/to/your/vault

默认位置 （如果自动检查 VAULT_PATH 未设置）：

  • ./.unihub-vault/UniHubVault （相对于项目根）
  • ~/Q/massage.kg/.unihub-vault/UniHubVault

MCP客户端配置

克劳德桌面

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上，或 %APPDATA%\Claude\claude_desktop_config.json 在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"
      }
    }
  }
}

光标IDE

添加 .cursor/mcp.json 在您的工作空间中：

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

风帆/Codeium

添加到MCP设置中：

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

通用MCP客户端

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

可用工具

问题管理（5个工具）

工具 说明
create_issue(name, body, tags?) 在中创建问题 10_Inbox，返回8个字符的ID
read_issue(iss_uniq_id) 通过唯一ID读取问题内容
update_issue(iss_uniq_id, content, append?) 更新或附加到问题
move_issue(iss_uniq_id, stage) 将问题移至舞台(10_Inbox, 20_Processing, 30_ToReview, 999_Finished)
list_issues(stage?) 列出阶段中的问题（默认值： 10_Inbox)

保险库操作（3个工具）

工具 说明
read_note(path) 从vault读取任何注释（相对于vault根的路径）
list_notes(directory?) 列出目录中的markdown文件
search_vault(query) 搜索全部 .md 文件（自动检测正则表达式与关键字）

状态（1个工具）

工具 说明
get_status() 仪表板：按阶段列出的问题+最近修改的注释

电报（3个工具）

工具 说明
set_telegram_webhook(url) 设置机器人webhook URL
check_telegram_webhook() 检查webhook状态
poll_telegram_updates() 轮询并将更新转发到本地webhook

问题生命周期

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

典型工作流程

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

艺名

支持全名和简称：

短 满
inbox 10_Inbox
processing 20_Processing
review 30_ToReview
finished 999_Finished

工具示例

创建和跟踪问题

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_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()
→ ## 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)

运行测试

uv run python test_issue_tools.py

这将运行一个涵盖整个问题生命周期的集成测试。

建筑

  • FastMCP MCP协议处理的服务器框架
  • 基于文件的存储 在stage目录中使用markdown文件
  • 路径安全 验证以防止目录遍历
  • 电报集成 通过bot代币 backend/.env

相关 MCP