vector-task-mcp: Instructions file for Claude Code

Vector Task MCP Server

Project Overview

MCP (Model Context Protocol) Server для управління задачами з використанням sqlite-vec для семантичного пошуку.

Technology Stack

• Python: 3.11.8 (requires >= 3.10)
• Package Manager: uv (сучасний Python package manager)
• Database: SQLite 3.43.2 + sqlite-vec extension
• Embeddings: sentence-transformers/all-MiniLM-L6-v2 (384-dimensional vectors)
• MCP Framework: FastMCP >= 0.3.0

Key Dependencies

• mcp>=0.3.0 - Model Context Protocol framework
• sqlite-vec>=0.1.6 - Vector search extension для SQLite
• sentence-transformers>=2.2.2 - Embedding models

Project Structure

• main.py - Entry point with uv script configuration
• requirements.txt - Python dependencies for pip/venv compatibility
• pyproject.toml - Modern Python project configuration
• .python-version - Python version specification (3.11)
• claude-desktop-config.example.json - Claude Desktop configuration template
• src/models.py - Data models and configuration
• src/security.py - Security validation and sanitization
• src/task_store.py - Vector task storage operations
• tasks.db - SQLite database for tasks

How to Run

Standalone

# Using uv (requires Python with SQLite extensions support)
uv run main.py --working-dir ./

# Alternative with conda Python (has SQLite extensions support)
~/miniconda3/envs/vector-mcp/bin/python main.py --working-dir ./

Configuration Options

• --working-dir - Working directory for task database (required, default: current directory)

  • Specifies the project directory where the memory/ subdirectory will be created
  • Database will be stored at {working-dir}/memory/tasks.db
  • Example: --working-dir /path/to/project → database at /path/to/project/memory/tasks.db

• --task-folder - Optional root directory for per-task folders (feature opt-in)

  • When set, every ROOT task gets its own folder named by its code (e.g. {--task-folder}/FEAT-44/) plus a generated task.md template.
  • Subtasks NEVER receive folders — only root tasks (parent_id IS NULL).
  • Status transitions rename/archive the folder automatically: completed → -on-review, done → Archive/{code} (top-level Archive), completed → in_progress reverts the rename.
  • Filesystem failures NEVER block DB operations — the manager logs warnings and returns silently. DB state is the source of truth.
  • Read APIs: task_get returns folder_path + folder_files for root tasks; task_folder_files(task_id|code) returns the same listing on demand.
  • Example: --task-folder /path/to/project/tasks → root task FEAT-12 gets /path/to/project/tasks/FEAT-12/task.md.