Out of Context
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Out of Context save a note about project architecture"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.)
Related MCP server: Markdown MCP Server
Quick Start
Installation
pip install hjeon139-mcp-outofcontextMCP 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 pathName 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/directoryBulk 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 registrationAppStateMiddleware: 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-depsRun 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 releaseSee 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 configurationContributing
Contributions welcome! Please:
Follow Conventional Commits format
Add tests for new functionality
Update documentation as needed
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:
Available Tools
5 toolsdelete_contextA
Delete context by name (forced eviction by agent). Supports both single and bulk operations.
Single: provide 'name' (str). Bulk: provide 'names' (list[str]) or 'name' as list[str]. For bulk operations, returns list of results with errors for missing contexts.
Inputs: name, names. Returns: object
get_contextA
Get context by name. Supports both single and bulk operations.
Single: provide 'name' (str). Bulk: provide 'names' (list[str]) or 'name' as list[str]. Returns context with 'text' (markdown body) and 'metadata' (from frontmatter). For bulk operations, returns list of results with errors for missing contexts.
Inputs: name, names. Returns: object
list_contextA
List all contexts, sorted by creation date (newest first).
Returns list of contexts with 'name', 'created_at', and 'preview' (first 100 chars). Optional 'limit' parameter to limit number of results.
Inputs: limit. Returns: object
put_contextA
Add or update context by name. Supports both single and bulk operations.
Single: provide 'name' (str), 'text' (str, markdown content), and optional 'metadata' (dict). Bulk: provide 'contexts' (list[dict]) where each dict has 'name', 'text', optional 'metadata'. Names must be filename-safe (alphanumeric, hyphens, underscores). Overwrites existing contexts with a warning. Contexts are stored as .mdc files (markdown with YAML frontmatter).
Inputs: name, text, metadata, contexts. Returns: object
search_contextA
Search contexts by query string.
Searches in both YAML frontmatter (metadata) and markdown body (text content). Returns matching contexts with 'name', 'text', 'metadata', and 'matches' (where query was found). Optional 'limit' parameter to limit number of results.
Inputs: query (required), limit. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct purpose (delete, get, list, put, search) with no overlap, making it easy for an agent to select the correct one.
All tools follow a consistent 'verb_context' pattern in snake_case, ensuring predictable and readable naming.
With 5 tools, the set is well-scoped for managing contexts, covering CRUD and search without unnecessary bloat.
The tool surface is complete for the domain: create/update (put), read (get/list), delete, and search—no obvious gaps.
Maintenance
Related MCP Connectors
shared AI-context layer for teams — persistent memory your agents search and update over MCP
Cross-tool persistent memory and context for AI assistants over MCP.
Persistent memory for AI agents to retain, retrieve, and recall conversation context through MCP.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn MCP server that extends AI agents' context window by providing tools to store, retrieve, and search memories, allowing agents to maintain history and context across long interactions.1MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP (Model Context Protocol) server for efficiently managing Markdown documents in Cursor AI IDE, supporting CRUD operations, search, and metadata management.-
- AlicenseNot gradedqualityDmaintenanceA local-first MCP server that turns a .context/ folder of markdown files into a searchable knowledge layer for AI coding agents.15 npm2MIT
- AlicenseAqualityDmaintenanceA local-first MCP server that gives AI coding assistants persistent, structured, human-readable memory for a software project by storing project knowledge as Markdown files in the project's .dev-context-memory/ folder.71MIT