Building Controlled Context with Markdown Reader MCP
We're in an interesting moment with AI tooling. Large language models can help us with everything from debugging code to writing documentation, but there's a gap between what they know and what we need them to understand about our specific context, projects, and way of working.
The Model Context Protocol (MCP) from Anthropic offers an elegant solution - a way to give AI assistants controlled access to specific resources and capabilities. After working with various AI tools and struggling with context management, I built markdown-reader-mcp, a simple MCP server that provides read-only access to markdown files across configured directories.
The Context Problem
When we work with AI assistants on technical projects, we often find ourselves repeatedly explaining the same concepts, copying and pasting the same documentation, or trying to describe complex systems that we've already documented elsewhere. The assistant doesn't know about our project structure, our coding standards, our deployment processes, or the specific challenges we're solving.
Traditional approaches involve either uploading files one by one or hoping the AI can infer context from conversation. Both approaches are inefficient and error-prone. We need something that sits between complete isolation and unrestricted access.
A Controlled Approach
The markdown-reader MCP server addresses this by providing two simple capabilities:
- Find markdown files with optional filtering and pagination
- Read markdown files by filename across multiple configured directories
The key insight is that markdown files often contain our most valuable context - documentation, guides, project notes, and structured knowledge. By making these discoverable and readable, we give AI assistants the ability to understand our specific domain without exposing sensitive code or data.
The server automatically ignores common directories like .git and node_modules, focusing only on the documentation and notes that matter. It's read-only by design, ensuring that assistants can consume context but never modify your files.
Primary Use Cases
The most immediate value comes from creating what I call "controlled personal collections" - curated sets of prompts, guidelines, and context that can be applied across all your AI interactions.
For example, you might have:
- Project documentation - README files, architecture decisions, deployment guides
- Personal prompts - Reusable instructions for common tasks like code reviews or blog writing
- Team guidelines - Coding standards, best practices, style guides
- Learning notes - Technical concepts, reference materials, troubleshooting guides
Instead of manually copying these into conversations, the AI can discover and read them as needed. This creates consistency across interactions and reduces the cognitive load of context management.
Beyond Personal Use
While individual productivity is the starting point, the real potential lies in team and organizational knowledge sharing. Imagine AI assistants that can automatically reference your team's deployment runbooks, understand your specific architecture patterns, or apply your organization's security guidelines.
The controlled nature of MCP makes this practical - you can precisely define what knowledge is available without exposing sensitive information or allowing modifications.
Getting Started
Setting up the markdown-reader MCP is straightforward:
- Install it via Claude Code:
claude mcp add markdown-reader - Configure directories in
~/.config/markdown-reader-mcp/markdown-reader-mcp.json - Start using natural language to find and read your markdown files
The configuration is simple - just specify which directories contain the markdown files you want to make available. The server handles discovery, filtering, and reading automatically.
Building on This Foundation
This tool represents a small step toward more intentional AI interactions. Instead of treating AI assistants as blank slates that need constant context, we can provide them with structured access to our existing knowledge.
The markdown-reader MCP is deliberately simple and aims to do this one thing well.
What matters is starting with controlled, purposeful access to the context that makes AI assistance more valuable. We're not just asking AI to help us - we're giving it the knowledge it needs to help us effectively.
The code is freely available on GitHub.