Out of Context

An MCP (Model Context Protocol) server for managing context using simple CRUD operations. Stores contexts as markdown files (.mdc) with YAML frontmatter, allowing agents to save, retrieve, search, and manage context by name.

Features

• Simple CRUD Operations: 5 basic tools for context management (put, list, get, search, delete)
• Markdown Storage: Contexts stored as .mdc files (markdown with YAML frontmatter)
• Agent-Recognizable Names: Use meaningful names instead of UUIDs
• Bulk Operations: Support for bulk put, get, and delete operations with robust parameter handling
• Pydantic Validation: Type-safe parameter validation with automatic schema generation
• Text Search: Search contexts by query string across metadata and content
• MCP Integration: Works with any MCP-compatible platform (Cursor, Claude Desktop, etc.)

Quick Start

Installation

pip install hjeon139-mcp-outofcontext

MCP Server Configuration

Add to your MCP platform configuration (e.g., Cursor or Claude Desktop):

{
  "mcpServers": {
    "out-of-context": {
      "command": "hjeon139_mcp_outofcontext",
      "env": {
        "OUT_OF_CONTEXT_STORAGE_PATH": ".out_of_context"
      }
    }
  }
}

Verify Installation

In your MCP platform, check that tools like put_context, list_context, get_context, search_context, and delete_context are available.

Usage Examples

Add Context

Single operation:

{
  "tool": "put_context",
  "arguments": {
    "name": "api-design-notes",
    "text": "# API Design Notes\n\nKey decisions about the REST API...",
    "metadata": {
      "type": "note",
      "tags": ["api", "design"]
    }
  }
}

Bulk operation:

{
  "tool": "put_context",
  "arguments": {
    "contexts": [
      {
        "name": "context-1",
        "text": "First context",
        "metadata": {"type": "note"}
      },
      {
        "name": "context-2",
        "text": "Second context"
      }
    ]
  }
}

List Contexts

{
  "tool": "list_context",
  "arguments": {
    "limit": 10
  }
}

Returns list of contexts sorted by creation date (newest first).

Get Context

Single operation:

{
  "tool": "get_context",
  "arguments": {
    "name": "api-design-notes"
  }
}

Bulk operation:

{
  "tool": "get_context",
  "arguments": {
    "names": ["context-1", "context-2", "context-3"]
  }
}

Search Contexts

{
  "tool": "search_context",
  "arguments": {
    "query": "API design",
    "limit": 5
  }
}

Searches in both YAML frontmatter (metadata) and markdown body (text content).

Delete Context

Single operation:

{
  "tool": "delete_context",
  "arguments": {
    "name": "old-context"
  }
}

Bulk operation:

{
  "tool": "delete_context",
  "arguments": {
    "names": ["context-1", "context-2"]
  }
}

Storage Format

Contexts are stored as .mdc files (markdown with YAML frontmatter) in the .out_of_context/contexts/ directory.

File format:

---
name: api-design-notes
created_at: 2025-12-14T12:51:27.123456
type: note
tags: [api, design]
---

# API Design Notes

Key decisions about the REST API design...

- Use RESTful conventions
- Version in URL path

Name requirements:

• Filename-safe: alphanumeric characters, hyphens, and underscores only
• Unique: overwriting an existing name replaces the old context (with warning)

Documentation

• Installation Guide - Setup and configuration
• Usage Guide - Detailed usage instructions
• Development Guide - Development setup and contribution guidelines
• API Documentation - Complete tool reference

Key Concepts

• Context: A markdown document with YAML frontmatter (metadata) and markdown body (content)
• Name: Agent-recognizable identifier (e.g., "api-design-notes", "bug-fix-context")
• Storage: Individual .mdc files in .out_of_context/contexts/ directory
• Bulk Operations: Process multiple contexts in a single call (put, get, delete)

Architecture

The server provides a simple file-based storage system built with FastMCP:

Key Components:

• FastMCP Server: Modern MCP server implementation with middleware support
• MDCStorage: Manages .mdc file operations (save, load, list, search, delete)
• CRUD Tools: 5 tool handlers using @mcp.tool() decorators for automatic registration
• AppStateMiddleware: Dependency injection pattern for clean state management

Storage:

• Each context is one .mdc file
• YAML frontmatter for metadata
• Markdown body for content
• Simple text-based search

Development

Setup

# Clone repository
git clone <repository-url>
cd out_of_context

# Create environment
hatch env create

# Install dependencies
hatch run update-deps

Run Tests

# Unit tests
hatch run pytest -m 'unit'

# Integration tests
hatch run pytest -m 'integration'

Code Quality

# Lint and format
hatch run lint-fix
hatch run fmt-fix

# Type check
hatch run typecheck

# Full release pipeline
hatch run release

See Development Guide for detailed setup and contribution guidelines.

Project Structure

out_of_context/
├── src/hjeon139_mcp_outofcontext/  # Main package
│   ├── fastmcp_server.py            # FastMCP instance + middleware
│   ├── main.py                      # Entry point
│   ├── tools/
│   │   ├── crud/                    # CRUD operations (put, get, delete)
│   │   └── query/                   # Query operations (list, search)
│   ├── storage/                     # MDC storage layer
│   ├── app_state.py                 # Application state
│   ├── config.py                    # Configuration
│   └── prompts.py                   # MCP prompts
├── tests/                           # Test files (195 tests)
├── docs/                            # Documentation
└── pyproject.toml                   # Project configuration

Contributing

Contributions welcome! Please:

1. Follow Conventional Commits format
2. Add tests for new functionality
3. Update documentation as needed
4. Run pre-commit checklist before submitting

See Development Guide for detailed contribution guidelines.

License

Apache 2.0 - See LICENSE file for details.

References

• MCP Protocol: Model Context Protocol
• Steering Documentation: docs/steering/ - Development guidelines

Status

Version: 1.0.0 (Launch Release)

Status: Production Ready

Features:

• ✅ Basic CRUD operations (put, list, get, search, delete)
• ✅ Markdown file storage (.mdc format)
• ✅ Agent-recognizable names
• ✅ Bulk operations support with robust parameter handling
• ✅ Pydantic validation for type-safe parameters
• ✅ Automatic JSON schema generation for MCP clients
• ✅ Text search across metadata and content
• ✅ Built with FastMCP for improved developer experience

Support

• Documentation: See docs/ directory
• Issues: Open an issue on GitHub
• Questions: Use GitHub Discussions

Acknowledgments

Built with:

• FastMCP - FastMCP framework for MCP servers
• Pydantic - Data validation
• PyYAML - YAML parsing