MCP 服务器

Out of Context

An MCP server for managing contextual data as markdown files with metadata, enabling agents to save, retrieve, search, and delete contexts using simple CRUD operations.

README

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