<div align="center"> <img src="assets/banner.svg" alt="Task Context MCP Server Banner" width="100%">

<p align="center"> <a href="https://pypi.org/project/task-context-mcp/"> <img src="https://img.shields.io/pypi/v/task-context-mcp.svg" alt="PyPI version"> </a> <a href="https://pypi.org/project/task-context-mcp/"> <img src="https://img.shields.io/pypi/pyversions/task-context-mcp.svg" alt="Python versions"> </a> <a href="https://opensource.org/licenses/MIT"> <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"> </a> </p> </div>

Task Context MCP Server

An MCP (Model Context Protocol) server for managing task contexts and artifacts to enable AI agents to autonomously manage and improve execution processes for repetitive task types.

Overview

Important Distinction: This system manages task contexts (reusable task types/categories), NOT individual task instances.

For example:

• Task Context: "Analyze applicant CV for Python developer of specific stack"
• NOT stored: Individual applicant details or specific CV analyses
• Stored: Reusable artifacts (practices, rules, prompts, learnings) applicable to ANY CV analysis of this type

This MCP server provides a SQLite-based storage system that enables AI agents to:

• Store and retrieve task contexts with associated artifacts (practices, rules, prompts, learnings)
• Perform full-text search across historical learnings and best practices using SQLite FTS5
• Manage artifact lifecycles with active/archived status tracking
• Enable autonomous process improvement with minimal user intervention
• Store multiple artifacts of each type per task context

Features

Core Functionality

• Task Context Management: Create, update, archive, and retrieve task contexts (reusable task types)
• Artifact Storage: Store multiple practices, rules, prompts, and learnings for each task context
• Full-Text Search: Efficient search across all artifacts using SQLite FTS5
• Lifecycle Management: Track active vs archived artifacts with reasons
• Transaction Safety: ACID compliance for all database operations

MCP Tools Available

1. get_active_task_contexts - Get all currently active task contexts
2. create_task_context - Create a new task context with summary and description
3. get_artifacts_for_task_context - Retrieve all artifacts for a specific task context
4. create_artifact - Create a new artifact (multiple per type allowed)
5. update_artifact - Update an existing artifact's summary and/or content
6. archive_artifact - Archive artifacts with optional reason
7. search_artifacts - Full-text search across all artifacts
8. reflect_and_update_artifacts - Reflect on learnings and get prompted to update artifacts

Installation

Prerequisites

• Python 3.12+
• uv package manager

Setup

# Clone the repository
git clone https://github.com/l0kifs/task-context-mcp.git
cd task-context-mcp

# Install dependencies
uv sync

# Run tests
uv run pytest

Usage

Running the MCP Server

# Run directly
uv run python src/task_context_mcp/main.py

# Or with uv run script
uv run task-context-mcp

MCP Client Configuration

For VS Code/Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "task-context": {
      "command": "uvx",
      "args": ["task-context-mcp@latest"]
    }
  }
}

MCP Tools Available

The server provides the following tools via MCP:

1. get_active_task_contexts

Get all active task contexts in the system with their metadata.

• Returns: List of active task contexts with id, summary, description, creation/update dates

2. create_task_context

Create a new task context (reusable task type) with summary and description.

• Parameters:
  • summary (string): Brief task context description (e.g., "CV Analysis for Python Developer")
  • description (string): Detailed task context description
• Returns: Created task context information

3. get_artifacts_for_task_context

Retrieve all active artifacts for a specific task context.

• Parameters:
  • task_context_id (string): ID of the task context
  • artifact_types (optional list): Types to retrieve ('practice', 'rule', 'prompt', 'result')
  • include_archived (boolean): Whether to include archived artifacts
• Returns: All matching artifacts with content

4. create_artifact

Create a new artifact for a task context. Multiple artifacts of the same type are allowed.

• Parameters:
  • task_context_id (string): Associated task context ID
  • artifact_type (string): Type ('practice', 'rule', 'prompt', 'result')
  • summary (string): Brief description
  • content (string): Full artifact content
• Returns: Created artifact information

Artifact Types:

• practice: Best practices and guidelines for executing the task type
• rule: Specific rules and constraints to follow
• prompt: Template prompts useful for the task type
• result: General patterns and learnings from past work (NOT individual execution results)

5. update_artifact

Update an existing artifact's summary and/or content.

• Parameters:
  • artifact_id (string): ID of the artifact to update
  • summary (optional string): New summary
  • content (optional string): New content
• Returns: Updated artifact information

6. archive_artifact

Archive an artifact, marking it as no longer active.

• Parameters:
  • artifact_id (string): ID of artifact to archive
  • reason (optional string): Reason for archiving
• Returns: Archived artifact information

7. search_artifacts

Perform full-text search across all artifacts.

• Parameters:
  • query (string): Search query
  • limit (integer): Maximum results (default: 10)
• Returns: Matching artifacts ranked by relevance

8. reflect_and_update_artifacts

Reflect on task execution learnings and get prompted to update artifacts autonomously.

• Parameters:
  • task_context_id (string): ID of the task context used for this work
  • learnings (string): What was learned during task execution (mistakes, corrections, patterns, etc.)
• Returns: Reflection summary with current artifacts and required actions
• Purpose: Ensures agents autonomously manage artifacts by explicitly prompting them to create/update/archive based on their learnings

Architecture

Database Schema

• task_contexts: Task context definitions with metadata and status tracking
• artifacts: Artifact storage with lifecycle management (multiple per type per context)
• artifacts_fts: FTS5 virtual table for full-text search indexing

Database Migrations: The project uses Alembic for automatic schema migrations. When you modify the database models, Alembic automatically detects changes and updates the database. See docs/MIGRATIONS.md for details.

Key Components

• src/task_context_mcp/main.py: MCP server implementation with FastMCP
• src/task_context_mcp/database/models.py: SQLAlchemy ORM models
• src/task_context_mcp/database/database.py: Database operations and FTS5 management
• src/task_context_mcp/database/migrations.py: Alembic migration utilities
• src/task_context_mcp/config/: Configuration management with Pydantic settings
• alembic/: Database migration scripts and configuration

Technology Stack

• Database: SQLite 3.35+ with FTS5 extension
• ORM: SQLAlchemy 2.0+ for type-safe database operations
• Migrations: Alembic 1.17+ for automatic schema migrations
• MCP Framework: FastMCP for Model Context Protocol implementation
• Configuration: Pydantic Settings for environment-based config
• Logging: Loguru for structured, multi-level logging
• Development: UV for Python package and dependency management

Business Requirements Alignment

This implementation fulfills all requirements from docs/BRD.md:

• ✅ Task Context Catalog: UUID-based task context identification with metadata
• ✅ Artifact Storage: Lifecycle management with active/archived status, multiple per type
• ✅ Full-Text Search: FTS5-based search with BM25 ranking
• ✅ Context Loading: Automatic retrieval based on task context matching
• ✅ Autonomous Updates: Agent-driven improvements with feedback loops
• ✅ ACID Compliance: Transaction-based operations with SQLite
• ✅ Minimal Query Processing: Support for natural language task context matching

Use Case Scenarios

Scenario 1: Working on a New Task Type

1. User Request: "Help me analyze this CV for a Python developer position"
2. Agent Analysis: Agent analyzes the request and identifies it as a CV analysis task type
3. Task Context Discovery: Agent calls get_active_task_contexts to check for existing similar contexts
4. Task Context Creation: No matching context found, so agent calls create_task_context with:
   • Summary: "CV Analysis for Python Developer"
   • Description: "Analyze applicant CVs for Python developer positions with specific tech stack requirements"
5. Context Loading: Agent calls get_artifacts_for_task_context to load any existing artifacts
6. Task Execution: Agent uses loaded artifacts (practices, rules, prompts) to analyze the CV
7. Artifact Creation: Based on learnings, agent calls create_artifact to store successful approaches

Scenario 2: Continuing Work on Existing Task Type

1. User Request: "Analyze another CV for a Python developer"
2. Task Context Matching: Agent calls get_active_task_contexts and finds matching context by summary/description
3. Context Retrieval: Agent calls get_artifacts_for_task_context with the context ID to load all relevant artifacts
4. Task Execution: Agent uses the loaded context (practices, rules, prompts, learnings) to analyze the new CV
5. Process Improvement: Agent refines artifacts based on current execution and user feedback

Scenario 3: Finding Similar Past Work

1. User Request: "Help me optimize this database query"
2. Search for Inspiration: Agent calls search_artifacts with keywords like "database optimization" or "query performance"
3. Review Results: Agent examines returned artifacts for similar past approaches
4. Adapt Patterns: Agent adapts successful patterns from historical artifacts to current task
5. Store New Artifacts: Agent creates new artifacts documenting the current successful approach

Scenario 4: Autonomous Process Improvement

1. Task Completion: Agent completes a task and receives user feedback
2. Success Analysis: Agent analyzes whether the execution was successful
3. Artifact Updates:
   • Successful approaches: create_artifact to add new practices/rules/learnings
   • Refinements needed: update_artifact to improve existing artifacts
   • Outdated methods: archive_artifact with reason for archival
4. Future Benefit: Subsequent tasks of the same type automatically benefit from the improved artifacts

Configuration

The server uses the following configuration (via environment variables or .env file):

• TASK_CONTEXT_MCP__DATA_DIR: Data directory path (default: ./data)
• TASK_CONTEXT_MCP__DATABASE_URL: Database URL (default: sqlite:///./data/task_context.db)
• TASK_CONTEXT_MCP__LOGGING_LEVEL: Logging level (default: INFO)

Data Model

Task Contexts

• id: Unique UUID identifier
• summary: Brief task context description for matching
• description: Detailed task context description
• creation_date: When task context was created
• updated_date: When task context was last modified
• status: 'active' or 'archived'

Artifacts

• id: Unique UUID identifier
• task_context_id: Reference to associated task context
• artifact_type: 'practice', 'rule', 'prompt', or 'result'
• summary: Brief artifact description
• content: Full artifact content
• status: 'active' or 'archived'
• archived_at: Timestamp when archived (if applicable)
• archivation_reason: Reason for archiving
• created_at: When artifact was created

Note: Multiple artifacts of the same type can exist per task context. For example, a CV analysis context might have 5 different rules, 3 practices, 2 prompts, and several learnings.

Development

Running Tests

uv run pytest

Code Quality

# Lint and format
uv run ruff check
uv run ruff format

# Type checking
uv run ty

License

MIT License - see LICENSE file for details.