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

Component	Technology	Purpose
Vector DB	sqlite-vec	Vector storage and similarity search
Embeddings	sentence-transformers/all-MiniLM-L6-v2	384D text embeddings
MCP Framework	FastMCP	High-level tools-only server
Tag Normalization	Custom (src/normalization.py)	Semantic tag deduplication
Dependencies	uv script headers	Self-contained deployment
Security	Custom validation	Path/input sanitization
Testing	pytest + coverage	Comprehensive test suite

📁 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

Priority	Use Cases
critical	Production bugs, security issues, blockers
high	Important features, major improvements
medium	Regular features, enhancements (default)
low	Nice-to-have, refactoring, documentation

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)

Status	Description
draft	Task draft (not ready for execution)
pending	Task not yet started
in_progress	Currently being worked on
completed	Task finished (basic completion)
tested	Task completed and tested
validated	Task completed, tested, and validated
done	Final / archived; reachable as a jump from completed, tested, or validated
stopped	Task paused/blocked (can be resumed)
canceled	Task canceled (will not be 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:

Before	After
auth, authentication, auth-api, login	→ auth
db, database, database-setup	→ database
api, rest api, API	→ api

Hard Guards (Prevent Wrong Merges)

Guard	Rule	Example
Version	Different versions → NO	php8 ≠ php7
Numeric	Different numbers → NO	api1 ≠ api2
Facet	Different prefixes → NO	type:* ≠ domain:*
Prefix	Structured ≠ Plain	type:refactor ≠ refactor

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	Count	IDF Weight	Effect
api	70% of tasks	0.38	Low signal
vendor:stripe	3% of tasks	1.44	Strong signal

Tag Classification

Tags are classified by boost level:

Level	Boost	Examples
high	1.5	vendor:*, module:*, service:*
medium	1.0	Facet tags (domain:*, type:*), specific tags
low	0.5	General tags (api, backend, test)
filter_only	0.1	status:*, priority:*

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

Query	Finds Tasks About
"authentication"	Login, JWT, OAuth, user verification
"database optimization"	SQL queries, indexing, performance
"frontend components"	React, UI elements, styling
"API integration"	REST endpoints, webhooks, external services

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:

Task Count	Search Time	Storage Size	RAM Usage
1,000	<50ms	~5MB	~100MB
5,000	<100ms	~20MB	~200MB
10,000	<200ms	~40MB	~300MB

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:

Feature	Migration
tag_variants column	Auto-added via ALTER TABLE
canonical_tags table	Auto-created via CREATE TABLE IF NOT EXISTS
IDF reranking	Opt-in via use_idf_rerank=True

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.