Vector Task MCP Server

A secure, vector-based task management server for Claude Desktop using sqlite-vec and sentence-transformers. This MCP server provides intelligent task tracking with semantic search capabilities that enhance AI coding assistants by organizing and retrieving development tasks efficiently.

✨ Features

• 🔍 Semantic Search: Vector-based task search using 384-dimensional embeddings

• 💾 Persistent Storage: SQLite database with vector indexing via sqlite-vec

• 🏷️ Smart Organization: Priorities, tags, and subtasks for better task management

• 📋 Task Lifecycle: Track tasks from pending → in_progress → completed → tested → validated (or stopped)

• 🔐 Tag Normalization: Automatic tag deduplication with semantic similarity

• 📊 IDF Weights: Rare tags boost search relevance more than common tags

• 🎯 Tag Classification: Filter tags vs boost tags for smart ranking

• 🔄 Alias Scent: Original tag variants preserved for search context

• 🔒 Security First: Input validation, path sanitization, and resource limits

• ⚡ High Performance: Fast embedding generation with sentence-transformers

• 📈 Rich Statistics: Comprehensive task analytics and progress tracking

• 🔄 Hierarchical Tasks: Support for parent-child task relationships

• 📊 Priority Management: Organize tasks by priority (low, medium, high, critical)

• 💬 Task Comments: Add notes and updates to tasks without changing content

🛠️ Technical Stack

📁 Project Structure

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

🗂️ Organization Guide

This project is organized for clarity and ease of use:

• main.py - Start here! Main server entry point

• src/ - Core implementation (security, task storage)

• claude-desktop-config.example.json - Configuration template

New here? Start with main.py and claude-desktop-config.example.json

🚀 Quick Start

Prerequisites

• Python 3.10 or higher (recommended: 3.11)

• uv package manager

• Claude Desktop app

Installing uv (if not already installed):

macOS and Linux:

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

Verify installation:

uv --version

Installation

Option 1: Quick Install via uvx (Recommended)

The easiest way to use this MCP server - no cloning or setup required!

Once published to PyPI, you can use it directly:

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

Claude Desktop Configuration (using uvx):

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

Note: Publishing to PyPI is in progress.

Option 2: Install from Source (For Development)

1. Clone the project:

   git clone <repository-url>
   cd vector-task-mcp

2. Install dependencies (automatic with uv): Dependencies are automatically managed via inline metadata in main.py. No manual installation needed.

   To verify dependencies:

   uv pip list

3. Test the server:

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

4. Configure Claude Desktop:

   Copy the example configuration:

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

   Open Claude Desktop Settings → Developer → Edit Config, and add (replace paths with absolute paths):

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

   Important:

   • Use absolute paths, not relative paths

5. Restart Claude Desktop and look for the MCP integration icon.

Option 3: Install with pipx (Alternative)

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

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

Claude Desktop Configuration (using pipx):

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

📚 Usage Guide

Available Tools

Task Creation & Management

1. task_create - Create New Task

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

Create multiple tasks at once for batch operations

3. task_update - Update Task Fields

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

4. task_delete - Delete Task

Delete task with ID 123

5. task_delete_bulk - Delete Multiple Tasks

Delete tasks: [123, 124, 125]

Task Retrieval

6. task_list - List Tasks with Filters

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

7. task_get - Get Specific Task

Get task with ID 123

For ROOT tasks (parent_id IS NULL) when --task-folder is enabled, the response also includes folder_path (resolved folder location) and folder_files (recursive file listing).

7a. task_folder_files - List Files in Task Folder

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

Requires --task-folder. Provide exactly one of task_id or code. Subtasks are rejected. Returns {code, folder_path, files: [{path, relative}, ...]}.

8. task_last - Get Last Created Task

Show me the last task I created

9. task_next - Get Next Task to Work On

What should I work on next?

Returns in_progress task if any, otherwise next pending task.

Task Lifecycle

10. task_start - Start Task

Start working on task 123

Sets status to in_progress and records start time.

11. task_finish - Complete Task

Mark task 123 as completed

Sets status to completed and records finish time.

12. task_stop - Stop Task

Stop working on task 123

Sets status to stopped (can be resumed later).

13. task_resume - Resume Stopped Task

Resume task 123

Sets status back to in_progress.

Task Metadata

14. task_comment - Add/Update Comment

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

15. task_add_tag - Add Tag

Add tag "urgent" to task 123

16. task_remove_tag - Remove Tag

Remove tag "urgent" from task 123

17. task_get_all_tags - List All Tags

Show all tags used in tasks

Task Statistics

18. task_stats - Get Task Statistics

Show task statistics

Returns:

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

Tag Normalization Tools

19. tag_normalize_preview - Preview Tag Merges

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

Shows similar tags that can be merged into canonical forms.

20. tag_normalize_apply - Apply Tag Normalization

Apply tag normalization with optional dry_run

Merges variant tags into canonical forms and stores original variants in tag_variants.

21. tag_similarity - Compare Two Tags

Compare similarity between "auth" and "authentication"

Returns cosine similarity score (0.0-1.0).

22. canonical_tag_add - Add Canonical Mapping

Add mapping: "authentication" → "auth"

23. canonical_tag_remove - Remove Mapping

Remove mapping for "authentication"

24. canonical_tag_list - List All Mappings

List all canonical tag mappings

25. get_canonical_tags - List Canonical Tags

List all canonical tags only

Tag Intelligence Tools

26. tag_frequencies - Get Tag Frequencies & IDF Weights

Get tag frequencies with IDF weights

Returns frequency statistics and IDF weights for search ranking:

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

27. tag_weights - Get Simplified IDF Weights

Get IDF weights for all tags (for search ranking)

28. tag_classify - Classify Single Tag

Classify tag "vendor:stripe"

Returns boost level (high/medium/low/filter_only) for ranking.

29. tags_classify_batch - Classify Multiple Tags

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

30. search_explain - Search with Ranking Explanation

Search for "authentication" with ranking explanation

Shows how IDF weights, classification, and variants affect ranking.

Task Priorities

Task Status Lifecycle

Available statuses: draft, pending, in_progress, completed, tested, validated, done, stopped, canceled

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

🔧 Configuration

Command Line Arguments

# 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

Available Options:

• --working-dir (required): Directory where task database will be stored

• --task-folder (optional): Root directory for per-task folders (feature opt-in). When set, every ROOT task gets a folder named by its code (e.g. FEAT-12/) with an auto-generated task.md template. Subtasks never receive folders. Status transitions rename/archive the folder automatically: completed → -on-review, done → Archive/{code} (top-level Archive), revert on in_progress. Filesystem failures are logged and never block DB operations. Read APIs: task_get returns folder_path + folder_files for root tasks; the dedicated task_folder_files(task_id|code) tool returns the listing on demand. The project://info resource exposes the per-root folder summary.

• --timezone (optional): IANA timezone for displayed timestamps (default: UTC). Example: --timezone Europe/Kyiv

Working Directory Structure

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

Database Schema

tasks table:

• Core task data + tags (canonical) + tag_variants (original variants)

canonical_tags table:

• Predefined tag mappings (variant → canonical)

task_vectors table:

• 384-dimensional embeddings for semantic search

Security Limits

• Max task content: 10,000 characters

• Max bulk create: 50 tasks per operation

• Max bulk delete: 100 tasks per operation

• Max tags per task: 10 tags

• Path validation: Blocks suspicious characters

🎯 Use Cases

For Individual Developers

# 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"

For Team Workflows

# 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"

For Project Management

# 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"

🏷️ Tag Normalization

Overview

Tag normalization reduces tag fragmentation by merging semantically similar tags:

Hard Guards (Prevent Wrong Merges)

Substring Boost

Tags that are substrings get a small boost if:

• Shorter word ≥ 4 characters

• Not in stop-words (api, ui, db, etc.)

Example: "laravel" ⊂ "laravel framework" → boost to 0.95

Facet Model (Colon Tags)

Tags with colons (prefix:value) are treated as structured facets:

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

Rules:

• Same prefix can merge if similar: type:refactor ↔ type:refactoring ✅

• Different prefixes never merge: type:* ↔ domain:* ❌

• Structured never merges with plain: type:* ↔ refactor ❌

Tag Variants (Alias Scent)

When tags are migrated, original variants are preserved:

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

Variants provide:

• Context for search ranking

• Explanation in UI ("Why auth? Because was login/authentication")

• Rerank signal for queries

📊 IDF Weights & Tag Classification

IDF (Inverse Document Frequency)

Rare tags boost relevance more than common tags:

idf_weight = 1 / log(1 + frequency)

Tag Classification

Tags are classified by boost level:

Search Ranking

Final search score combines:

1. Vector similarity (cosine distance)

2. IDF weight (rare tags boost more)

3. Tag classification (high > medium > low > filter)

4. Variant bonus (tasks with tag_variants get small boost)

🔍 How Semantic Search Works

The server uses sentence-transformers to convert tasks into 384-dimensional vectors that capture semantic meaning:

Example Searches

Hierarchical Tasks

Create parent-child relationships:

# 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 Statistics

The task_stats tool provides comprehensive insights:

{
  "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
}

Statistics Fields Explained

• total_tasks: Total number of tasks in database

• by_status: Task count breakdown by status (pending, in_progress, completed, tested, validated, stopped)

• pending_count: Tasks not yet started

• in_progress_count: Tasks currently being worked on

• completed_count: Tasks finished (basic completion)

• tested_count: Tasks that have been tested

• validated_count: Tasks that have been validated

• stopped_count: Tasks that were stopped (can be resumed)

• with_subtasks: Number of parent tasks with subtasks

• next_task_id: ID of the next task to work on (smart selection)

🛡️ Security Features

Input Validation

• Sanitizes all user input to prevent injection attacks

• Removes control characters and null bytes

• Enforces length limits on all content

Path Security

• Validates and normalizes all file paths

• Prevents directory traversal attacks

• Blocks suspicious character patterns

Resource Limits

• Limits bulk operations and individual task size

• Prevents database bloat

• Implements safe transaction handling

SQL Safety

• Uses parameterized queries exclusively

• No dynamic SQL construction from user input

• SQLite WAL mode for safe concurrent access

🔧 Troubleshooting

Common Issues

Server Not Starting

# 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+

Claude Desktop Not Connecting

1. Verify absolute paths in configuration

2. Check Claude Desktop logs: ~/Library/Logs/Claude/

3. Restart Claude Desktop after config changes

4. Test server manually before configuring Claude

Task Search Not Working

• Verify sentence-transformers model downloaded successfully

• Check database file permissions

• Try broader search terms

• Review task content for relevance

Debug Mode

Run the server manually to see detailed logs:

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

🚀 Advanced Usage

Task Organization Strategies

By Project Phase

Use tags to organize by development phase:

• ["phase-1", "mvp", "core-features"]

• ["phase-2", "optimization", "performance"]

• ["phase-3", "polish", "ux-improvements"]

By Technology Stack

• ["frontend", "react", "typescript"]

• ["backend", "python", "fastapi"]

• ["devops", "docker", "kubernetes"]

By Feature Domain

• ["authentication", "security", "jwt"]

• ["payments", "stripe", "billing"]

• ["analytics", "reporting", "dashboard"]

Integration with Development Workflow

Agile Sprint Planning

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

Bug Tracking

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

Feature Development

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

📈 Performance Benchmarks

Based on testing with various dataset sizes:

Tested on MacBook Air M1 with sentence-transformers/all-MiniLM-L6-v2

🧪 Test Coverage

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

Total: 105 tests

Run tests:

uv run pytest tests/ -v

🔄 Backward Compatibility

New features are backward compatible:

Existing databases work without changes. New columns/tables added automatically on first run.

🤝 Contributing

This is a standalone MCP server designed for personal/team use. For improvements:

1. Fork the repository

2. Modify as needed for your use case

3. Test thoroughly with your specific requirements

4. Share improvements via pull requests

📄 License

This project is released under the MIT License.

🙏 Acknowledgments

• sqlite-vec: Alex Garcia's excellent SQLite vector extension

• sentence-transformers: Nils Reimers' semantic embedding library

• FastMCP: Anthropic's high-level MCP framework

• Claude Desktop: For providing the MCP integration platform

Built for developers who want intelligent task management with semantic search capabilities.