Vector Task MCP

矢量任务MCP服务器

A. 基于矢量的安全任务管理服务器 适用于Claude Desktop sqlite-vec 和 sentence-transformers该MCP服务器提供具有语义搜索功能的智能任务跟踪，通过高效组织和检索开发任务来增强AI编码助手。

✨ 特性

• 🔍 语义搜索：使用384维嵌入进行基于向量的任务搜索
• 💾 永久存储：SQLite数据库，通过矢量索引 sqlite-vec
• 🏷️ 智能组织：优先级、标签和子任务，以实现更好的任务管理
• 📋 任务生命周期：跟踪待处理的任务→ 正在进行中→ 完成→ 测试过的→ 已验证（或已停止）
• 🔐 标签标准化：具有语义相似性的自动标签重复数据删除
• 📊 IDF重量：稀有标签比普通标签更能提高搜索相关性
• 🎯 标签分类：智能排名的过滤标签与增强标签
• 🔄 Alias香味：保留原始标签变体以用于搜索上下文
• 🔒 安全第一：输入验证、路径清理和资源限制
• ⚡ 高性能：快速嵌入生成 sentence-transformers
• 📈 丰富的统计数据：全面的任务分析和进度跟踪
• 🔄 分层任务：支持父子任务关系
• 📊 优先级管理：按优先级（低、中、高、关键）组织任务
• 💬 任务备注：在不更改内容的情况下为任务添加注释和更新

🛠️ 技术栈

📁 项目结构

vector-task-mcp/
├── main.py                              # Main MCP server entry point
├── README.md                            # This documentation
├── requirements.txt                     # Python dependencies
├── pyproject.toml                       # Modern Python project config
├── .python-version                      # Python version specification
├── claude-desktop-config.example.json  # Claude Desktop config example
│
├── src/                                # Core package modules
│   ├── __init__.py                    # Package initialization
│   ├── models.py                      # Data models & configuration
│   ├── security.py                    # Security validation & sanitization
│   ├── task_store.py                  # SQLite-vec task operations
│   ├── embeddings.py                  # Embedding model wrapper
│   └── normalization.py               # Tag normalization & classification
│
├── tests/                             # Test suite
│   ├── test_task_store.py            # Task store tests
│   └── test_normalization.py         # Normalization tests
│
└── .gitignore                         # Git exclusions

🗂️ 组织指南

本项目的组织结构清晰易用：

• main.py -从这里开始！主服务器入口点
• src/ -核心实施（安全、任务存储）
• claude-desktop-config.example.json -配置模板

新来的？ 从...开始 main.py 和 claude-desktop-config.example.json

🚀 快速开始

先决条件

• Python 3.10或更高版本（推荐：3.11）
• 紫外线 包管理器
• Claude桌面应用程序

安装uv （如果尚未安装）：

macOS和Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

验证安装：

uv --version

安装

选项1：通过uvx快速安装（推荐）

使用此MCP服务器的最简单方法-无需克隆或设置！

一旦发布到PyPI，您可以直接使用它：

# Run without installation (like npx)
uvx vector-task-mcp --working-dir /path/to/your/project

Claude桌面配置 （使用uvx）：

{
  "mcpServers": {
    "vector-task": {
      "command": "uvx",
      "args": [
        "vector-task-mcp",
        "--working-dir",
        "/absolute/path/to/your/project"
      ]
    }
  }
}

备注：正在向PyPI发布。

选项2：从源代码安装（用于开发）

1. 克隆该项目:

   git clone 
   cd vector-task-mcp

1. 安装依赖项 （紫外线自动）：

依赖关系是通过main.py中的内联元数据自动管理的。不需要手动安装。

要验证依赖关系，请执行以下操作：

   uv pip list

1. 测试服务器:

   # Test with sample working directory
   uv run main.py --working-dir ./test-tasks

1. 配置Claude桌面:

复制示例配置：

   cp claude-desktop-config.example.json ~/path/to/your/config/

打开克劳德桌面设置→ 开发者→ 编辑Config，并添加（用绝对路径替换路径）：

   {
     "mcpServers": {
       "vector-task": {
         "command": "uv",
         "args": [
           "run",
           "/absolute/path/to/vector-task-mcp/main.py",
           "--working-dir",
           "/your/project/path"
         ]
       }
     }
   }

重要提示：

- 使用绝对路径，而不是相对路径

1. 重新启动克劳德桌面 并查找MCP集成图标。

选项3：用管道安装（替代方案）

# Install globally (once published to PyPI)
pipx install vector-task-mcp

# Run
vector-task-mcp --working-dir /path/to/your/project

Claude桌面配置 （使用pipx）：

{
  "mcpServers": {
    "vector-task": {
      "command": "vector-task-mcp",
      "args": [
        "--working-dir",
        "/absolute/path/to/your/project"
      ]
    }
  }
}

📚 使用指南

可用工具

任务创建和管理

1. task_create -创建新任务

Create a new task:
Title: "Implement user authentication"
Content: "Add JWT-based authentication with refresh tokens"
Priority: high
Tags: ["auth", "backend", "security"]

2. task_create_bulk -创建多个任务

Create multiple tasks at once for batch operations

3. task_update -更新任务字段

Update task 123:
- Status: in_progress
- Priority: critical
- Title: "Updated title"

4. task_delete -删除任务

Delete task with ID 123

5. task_delete_bulk -删除多个任务

Delete tasks: [123, 124, 125]

任务检索

6. task_list -使用筛选器列出任务

List tasks:
- Status: pending
- Query: "authentication"
- Limit: 10

7. task_get -获取特定任务

Get task with ID 123

对于ROOT任务(parent_id IS NULL)何时 --task-folder 启用后，响应 还包括 folder_path （已解析文件夹位置）和 folder_files （递归文件列表）。

7a。 task_folder_files -列出任务文件夹中的文件

List files in folder for task 123 (or by code "FEAT-12")

需要 --task-folder。请提供以下内容之一 task_id 或 code.子任务 被拒绝。退货 {code, folder_path, files: [{path, relative}, ...]}.

8. task_last -获取上次创建的任务

Show me the last task I created

9. task_next -获取下一个要处理的任务

What should I work on next?

返回in_progress任务（如果有），否则返回下一个挂起的任务。

任务生命周期

10. task_start -启动任务

Start working on task 123

将状态设置为in_progress并记录开始时间。

11. task_finish -完成任务

Mark task 123 as completed

将状态设置为已完成并记录完成时间。

12. task_stop -停止任务

Stop working on task 123

将状态设置为已停止（稍后可以恢复）。

13. task_resume -恢复已停止的任务

Resume task 123

将状态设置回in_progress。

任务元数据

14. task_comment -添加/更新评论

Add comment to task 123:
"Updated API endpoint to use v2, all tests passing"

15. task_add_tag -添加标签

Add tag "urgent" to task 123

16. task_remove_tag -删除标签

Remove tag "urgent" from task 123

17. task_get_all_tags -列出所有标签

Show all tags used in tasks

任务统计

18. task_stats -获取任务统计信息

Show task statistics

退货：

{
  "total_tasks": 45,
  "by_status": {
    "pending": 20,
    "in_progress": 3,
    "completed": 20,
    "stopped": 2
  },
  "with_subtasks": 5,
  "next_task_id": 12
}

标签规范化工具

19. tag_normalize_preview -预览标签合并

Preview which tags can be merged:
- threshold: 0.90 (strict) or 0.85 (aggressive)

显示可以合并到规范形式中的类似标记。

20. tag_normalize_apply -应用标签规范化

Apply tag normalization with optional dry_run

将变体标签合并为规范形式，并将原始变体存储在 tag_variants.

21. tag_similarity -比较两个标签

Compare similarity between "auth" and "authentication"

返回余弦相似性得分（0.0-1.0）。

22. canonical_tag_add -添加规范映射

Add mapping: "authentication" → "auth"

23. canonical_tag_remove -删除映射

Remove mapping for "authentication"

24. canonical_tag_list -列出所有映射

List all canonical tag mappings

25. get_canonical_tags -列出规范标签

List all canonical tags only

标签智能工具

26. tag_frequencies -获取标签频率和IDF权重

Get tag frequencies with IDF weights

返回搜索排名的频率统计数据和IDF权重：

{
  "api": {"count": 10, "frequency": 0.4, "idf_weight": 0.621},
  "vendor:stripe": {"count": 1, "frequency": 0.04, "idf_weight": 1.443}
}

27. tag_weights -获取简化的IDF权重

Get IDF weights for all tags (for search ranking)

28. tag_classify -对单个标签进行分类

Classify tag "vendor:stripe"

返回排名的提升级别（高/中/低/仅限filter_only）。

29. tags_classify_batch -对多个标签进行分类

Classify tags: ["vendor:stripe", "api", "status:pending"]

30. search_explain -搜索与排名说明

Search for "authentication" with ranking explanation

显示IDF权重、分类和变体如何影响排名。

任务优先级

任务状态生命周期

可用状态: draft, pending, in_progress, completed, tested, validated, done, stopped, canceled

draft → pending → in_progress → completed → tested → validated → done
                       ↓                     ↓ ↓ ↓
                   stopped/canceled       (jump-to-done)

🔧 配置

命令行参数

# Run with uv (recommended)
uv run main.py --working-dir /path/to/project

# Working directory is where task database will be stored
uv run main.py --working-dir ~/projects/my-project

可用选项：

• --working-dir （必填）：存储任务数据库的目录
• --task-folder （可选）：每个任务文件夹的根目录（功能选择加入）。

设置后，每个ROOT任务都会获得一个文件夹，该文件夹由其 code （例如。 FEAT-12/) 自动生成 task.md 模板。子任务从不接收文件夹。 状态转换自动重命名/存档文件夹： completed → -on-review, done → Archive/{code} （顶级存档），恢复 in_progress. 文件系统故障会被记录下来，并且永远不会阻止数据库操作。 阅读API： task_get 回报 folder_path + folder_files 用于根任务； 专用 task_folder_files(task_id|code) 工具按需返回列表。 这 project://info 资源公开每个根文件夹的摘要。

• --timezone （可选）：显示时间戳的IANA时区（默认：UTC）。

例子： --timezone Europe/Kyiv

工作目录结构

your-project/
├── memory/
│   └── tasks.db              # SQLite database with task vectors
├── src/                      # Your project files
└── other-files...

数据库模式

任务表:

• 核心任务数据+ tags （正典）+ tag_variants （原始变体）

canonical_tags表:

• 预定义标记映射（变体→ 规范）

task_vectors表:

• 384维语义搜索嵌入

安全限制

• 最大任务内容：10000个字符
• 最大批量创建：每次操作50个任务
• 最大批量删除：每次操作100个任务
• 每个任务的最大标签数：10个标签
• 路径验证：阻止可疑字符

🎯 用例

对于个人开发者

# Track feature development
"Implement OAuth2 integration with Google and GitHub providers"

# Track bug fixes
"Fix memory leak in WebSocket connection handler"

# Track learning tasks
"Learn and implement Redis caching for API responses"

对于团队工作流

# Sprint planning
"Sprint 23: Redesign user dashboard with new analytics"

# Code review tasks
"Review PR #456: Database migration for user preferences"

# Infrastructure tasks
"Set up CI/CD pipeline for automated testing and deployment"

项目管理

# Epic-level tasks
"User Management System" (parent task)
  → "User registration" (subtask)
  → "Email verification" (subtask)
  → "Password reset" (subtask)

# Milestone tracking
"v2.0 Release Preparation"

# Technical debt
"Refactor legacy authentication module to use new security library"

🏷️ 标签标准化

概述

标签规范化通过合并语义相似的标签来减少标签碎片：

硬防护（防止错误合并）

变电站升压

如果满足以下条件，作为子字符串的标签将得到小幅提升：

• 短单词≥4个字符
• 不用停用词（api、ui、db等）

例子： "laravel" ⊂ "laravel framework" → 提高到0.95

面部模型（结肠标签）

带有冒号的标签(prefix:value)被视为结构化小面：

type:refactor     ← facet: "type", value: "refactor"
vendor:stripe     ← facet: "vendor", value: "stripe"
module:terminal   ← facet: "module", value: "terminal"

规则：

• 如果相似，相同的前缀可以合并： type:refactor ↔ type:refactoring ✅
• 不同的前缀从不合并： type:* ↔ domain:* ❌
• 结构化永远不会与普通合并： type:* ↔ refactor ❌

标签变体（别名气味）

迁移标记时，保留原始变体：

{
  "tags": ["auth"],
  "tag_variants": ["authentication", "auth-api", "login"]
}

变体提供：

• 搜索排名的上下文
• UI中的解释（“为什么进行身份验证？因为是登录/身份验证”）
• 重新排列查询信号

📊 IDF重量和标签分类

IDF（反向文档频率）

稀有标签比普通标签更能提高相关性：

idf_weight = 1 / log(1 + frequency)

标签分类

标签按增强级别分类：

搜索排名

最终搜索分数组合如下：

1. 向量相似性 （余弦距离）
2. IDF重量 （稀有标签提升更多）
3. 标签分类 （高>中>低>过滤器）
4. 变体奖金 （带有tag_variants的任务得到小幅提升）

🔍 语义搜索的工作原理

服务器使用 句子变换器 将任务转换为捕获语义含义的384维向量：

搜索示例

分层任务

建立亲子关系：

# Create parent task
task_create(title="User Management", content="Complete user system")
# Returns: task_id = 100

# Create subtasks
task_create(title="User Registration", content="...", parent_id=100)
task_create(title="Email Verification", content="...", parent_id=100)
task_create(title="Password Reset", content="...", parent_id=100)

📊 任务统计

这 task_stats 该工具提供全面的见解：

{
  "total_tasks": 247,
  "by_status": {
    "pending": 120,
    "in_progress": 8,
    "completed": 80,
    "tested": 20,
    "validated": 10,
    "stopped": 9
  },
  "pending_count": 120,
  "in_progress_count": 8,
  "completed_count": 80,
  "tested_count": 20,
  "validated_count": 10,
  "stopped_count": 9,
  "with_subtasks": 15,
  "next_task_id": 45
}

统计字段说明

• 总任务数：数据库中的任务总数
• by_status：按状态（待定、进行中、已完成、已测试、已验证、已停止）细分的任务计数
• 支出_计数：任务尚未开始
• inprogress_count：当前正在处理的任务
• 已完成_计数：任务已完成（基本完成）
• 测试计数：已测试的任务
• validated_count：已验证的任务
• 停止计数：已停止的任务（可以恢复）
• with_s子任务：包含子任务的父任务数
• next_task_id：下一个要处理的任务的ID（智能选择）

🛡️ 安全功能

输入验证

• 对所有用户输入进行消毒，以防止注射攻击
• 删除控制字符和空字节
• 对所有内容强制执行长度限制

路径安全

• 验证并规范所有文件路径
• 防止目录遍历攻击
• 阻止可疑的字符模式

资源限制

• 限制批量操作和单个任务大小
• 防止数据库膨胀
• 实现安全的事务处理

SQL安全

• 仅使用参数化查询
• 用户输入中没有动态SQL构造
• SQLite WAL模式用于安全并发访问

🔧 故障排除

常见问题

服务器未启动

# Check if uv is installed
uv --version

# Test server manually
uv run main.py --working-dir ./test

# Check Python version
python --version  # Should be 3.10+

克劳德桌面未连接

1. 验证配置中的绝对路径
2. 检查克劳德桌面日志： ~/Library/Logs/Claude/
3. 配置更改后重新启动Claude Desktop
4. 在配置Claude之前手动测试服务器

任务搜索不起作用

• 验证句子转换器模型下载成功
• 检查数据库文件权限
• 尝试更广泛的搜索词
• 审查任务内容的相关性

调试模式

手动运行服务器以查看详细日志：

uv run main.py --working-dir ./debug-test

🚀 高级用法

任务组织策略

按项目阶段

使用标签按开发阶段组织：

• ["phase-1", "mvp", "core-features"]
• ["phase-2", "optimization", "performance"]
• ["phase-3", "polish", "ux-improvements"]

按技术栈

• ["frontend", "react", "typescript"]
• ["backend", "python", "fastapi"]
• ["devops", "docker", "kubernetes"]

按功能域

• ["authentication", "security", "jwt"]
• ["payments", "stripe", "billing"]
• ["analytics", "reporting", "dashboard"]

与开发工作流集成

敏捷Sprint计划

Create sprint backlog tasks with priorities
Track progress with task_start/task_finish
Use task_stats for sprint reports

缺陷追踪系统

Create bug tasks with "critical" priority
Add tags: ["bug", "production", "hotfix"]
Use comments for debugging notes

功能开发

Create parent task for feature
Add subtasks for implementation steps
Track each subtask through lifecycle

📈 性能基准

基于不同数据集大小的测试：

*在配备句子转换器的MacBook Air M1上进行了测试/全MiniLM-L6-v2*

🧪 测试覆盖率

tests/
├── test_task_store.py     # 60 tests - Task store operations
└── test_normalization.py  # 45 tests - Tag normalization

Total: 105 tests

运行测试：

uv run pytest tests/ -v

🔄 向后兼容

新功能向后兼容：

现有数据库无需更改即可工作。首次运行时自动添加的新列/表。

🤝 贡献

这是一个独立的MCP服务器，专为个人/团队使用而设计。为了改进：

1. 分叉 存储库
2. 修改 根据您的用例需要
3. 测试 完全符合您的具体要求
4. 分享 通过pull请求进行改进

📄 许可证

该项目在MIT许可证下发布。

🙏 致谢

• sqlite-vc：Alex Garcia出色的SQLite向量扩展
• 句子变换器：Nils Reimers的语义嵌入库
• FastMCP：Anthropic的高级MCP框架
• 克劳德桌面版：用于提供MCP集成平台

______________________________________________________________________

专为希望使用语义搜索功能进行智能任务管理的开发人员而构建。