ContextForge MCP Lab

Overview

ContextForge MCP Lab is a local MCP-style data access server for working with task records and seeded documents through controlled tool functions. It uses Python, SQLite, JSON seed manifests, and sample text files to model how an AI-facing tool layer can expose useful application actions without exposing unrestricted database access.

The project is intentionally small: it provides a reproducible local database, a command-line tool dispatcher, and tests around the task and document workflows.

Related MCP server: Hoard

Features

• MCP-style named tool interface

• SQLite database with tasks and documents tables

• JSON-based seed data for repeatable local setup

• Seeded sample documents loaded from text files

• Controlled task and document functions

• Input validation for IDs, statuses, search terms, titles, and descriptions

• Parameterized SQLite queries

• Configurable database path through .env

• Pytest coverage for database setup, seed loading, tool behavior, validation, and unknown tool rejection

Architecture

ContextForge MCP Lab is organized into a small set of layers:

• MCP-style tool interface: src/server.py dispatches named JSON-compatible tool calls, and src/tools.py exposes the registered task and document functions.

• Python service layer: tool functions validate the callable surface and delegate workflow-specific behavior to the database module.

• SQLite persistence layer: src/database.py owns schema creation, reads, writes, updates, deletes, and search queries.

• Seeded sample files: data/*.json defines seed metadata, while sample_files/*.txt provides document bodies.

• Tests: tests/ verifies database initialization, seed behavior, tool calls, validation, and rejection of unregistered tools.

Tools

Task functions:

• create_task(title, description, status="todo")

• list_tasks(status=None)

• search_tasks(query)

• complete_task(task_id)

• delete_task(task_id)

Document functions:

• list_documents()

• search_documents(query)

• get_document(document_id)

• summarize_document_metadata()

Data Model

The tasks table stores local task records:

• id: auto-incrementing integer primary key

• title: required task title

• description: required task description

• status: one of todo, in_progress, or done

• created_at: UTC timestamp

• completed_at: UTC timestamp set when a task is completed

The documents table stores seeded document metadata and content:

• id: auto-incrementing integer primary key

• filename: unique source filename

• title: document title

• category: document category

• summary: short document summary

• content: full text loaded from sample_files/

• created_at: UTC timestamp

Installation

cd contextforge-mcp-lab
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Optional environment setup:

cp .env.example .env

The default database path is data/contextforge.db.

Seeding the Demo Database

python -m src.seed_data

This rebuilds the demo database with five task records and five documents loaded from sample_files/.

Running Tests

python -m pytest

Example Usage

Call tools through the local command dispatcher:

python -m src.server list_tasks
python -m src.server search_documents --args '{"query": "maintenance"}'
python -m src.server create_task --args '{"title": "Capture demo screenshot", "description": "Save terminal output showing seeded data and passing tests."}'
python -m src.server complete_task --args '{"task_id": 1}'

The same functions can be called directly from Python:

from src.server import call_tool

tasks = call_tool("list_tasks")
matches = call_tool("search_documents", {"query": "policy"})
task = call_tool(
    "create_task",
    {
        "title": "Review document metadata",
        "description": "Check seeded document categories and summaries.",
    },
)
completed = call_tool("complete_task", {"task_id": task["id"]})

Security Notes

• There is no raw SQL tool.

• Callers can only use registered task and document functions.

• SQLite access uses parameterized queries.

• Input validation is applied before database operations.

• The repository contains demo data only.

• The sample files are fictional and do not contain personal data.

Project Structure

contextforge-mcp-lab/
  README.md
  SETUP.md
  PORTFOLIO_WRITEUP.md
  LICENSE
  requirements.txt
  pyproject.toml
  src/
    server.py
    database.py
    tools.py
    config.py
    seed_data.py
  tests/
    test_database.py
    test_tools.py
  docs/
    ARCHITECTURE.md
    DEMO_PLAN.md
  sample_files/
    marketing_campaign_notes.txt
    server_maintenance_log.txt
    customer_support_policy.txt
    research_brief_llm_evals.txt
    project_meeting_summary.txt
  data/
    sample_tasks.json
    sample_documents.json

Roadmap

• Real MCP client integration

• FastAPI demo layer

• Rate limiting for hosted demo endpoints

• GitHub Actions test workflow

• Containerized deployment