Context File MCP Service

A powerful Model Context Protocol (MCP) service for managing AI context files from local directories and GitHub repositories. Provides intelligent file watching, tag-based organization, and full-text search capabilities.

Features

✨ Dual Source Support

• Read from local filesystem directories
• Fetch from GitHub repositories (public and private)

🔍 File Watching

• Automatic detection of file changes (add, modify, delete)
• Real-time metadata and index updates
• Efficient monitoring with minimal overhead

🏷️ Smart Tagging & Categorization

• Extract tags from YAML frontmatter
• Parse inline hashtags from content
• Fast tag-based file discovery
• Metadata extraction (title, description, tags)

🔎 Full-Text Search

• Search across all context files
• Relevance-based ranking
• Filter by tags and sources
• Context snippets in results

🚀 Optimized Performance

• Intelligent caching
• Incremental updates
• Support for large repositories

Installation

Prerequisites

• Node.js 18+
• npm or yarn

Setup

1. Clone or download the service:

mkdir context-file-mcp
cd context-file-mcp

2. Install dependencies:

npm install @modelcontextprotocol/sdk@^0.5.0 @octokit/rest@^20.0.0 chokidar@^3.5.3

3. Create package.json:

{
  "name": "context-file-mcp",
  "version": "2.0.0",
  "type": "module",
  "bin": {
    "context-file-mcp": "./index.ts"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.5.0",
    "@octokit/rest": "^20.0.0",
    "chokidar": "^3.5.3"
  }
}

4. Save the service code as index.ts

5. Make it executable:

chmod +x index.ts

Configuration

For Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "context-files": {
      "command": "node",
      "args": ["/absolute/path/to/context-file-mcp/index.ts"]
    }
  }
}

For Claude Code

Add to your MCP settings:

macOS/Linux: ~/.config/claude-code/mcp_settings.json

Windows: %APPDATA%\claude-code\mcp_settings.json

{
  "mcpServers": {
    "context-files": {
      "command": "node",
      "args": ["/absolute/path/to/context-file-mcp/index.ts"]
    }
  }
}

Usage

Adding Sources

Local Directory:

Add a local source called 'project-docs' from /Users/me/project/docs with watching enabled

GitHub Repository:

Add a GitHub source called 'team-context' from owner 'mycompany' repo 'ai-context' path 'docs' with token 'ghp_...'

Managing Context Files

List Sources:

Show me all configured sources

List Files:

List all context files in 'project-docs'

Read Files:

Read the authentication.md context file from 'project-docs'

Read Multiple Files:

Read these context files from 'project-docs': authentication.md, database.md, api-guidelines.md

Search & Discovery

Full-Text Search:

Search for 'authentication flow' in my context files

Search with Tag Filter:

Search for 'database' in files tagged 'backend'

List All Tags:

Show me all available tags

Find by Tag:

Show me all context files tagged 'api'

Get Metadata:

What are the tags and description for api-guidelines.md in 'project-docs'?

Maintenance

Refresh File List:

Refresh the file list for 'project-docs'

Stop Watching:

Stop watching 'project-docs' for changes

Context File Format

Create context files with YAML frontmatter for optimal organization:

---
title: Authentication Guide
description: OAuth2 and JWT implementation guidelines
tags: [auth, security, api, backend]
---

# Authentication Guide

This guide covers our authentication approach using OAuth2 and JWT.

## OAuth2 Flow

Use #oauth2 for third-party authentication...

## JWT Tokens

Implement #jwt for session management...

Supported Formats

• Frontmatter tags: tags: [tag1, tag2, tag3]
• Array format:

  tags:
    - tag1
    - tag2
  

• Inline hashtags: #tag1 #tag2 within content

File Extensions

The service automatically detects these file types:

• .md - Markdown files
• .mdx - MDX files
• .txt - Plain text files
• .context - Context-specific files

API Reference

Tools

add_source

Add a new context file source.

Parameters:

• name (string, required): Identifier for the source
• type (string, required): "local" or "github"
• path (string, required): Directory path or GitHub repo path
• watch (boolean, optional): Enable file watching (local only)
• githubToken (string, optional): GitHub PAT for private repos
• owner (string, required for GitHub): Repository owner
• repo (string, required for GitHub): Repository name
• branch (string, optional): Branch name (default: "main")

list_sources

List all configured sources.

list_files

List files in a source.

Parameters:

• source (string, required): Source name

read_context_file

Read a single context file.

Parameters:

• source (string, required): Source name
• file (string, required): File path

read_multiple_context_files

Read multiple context files.

Parameters:

• source (string, required): Source name
• files (array, required): Array of file paths

search_context_files

Search across context files.

Parameters:

• query (string, required): Search query
• tags (array, optional): Filter by tags
• source (string, optional): Limit to specific source

list_tags

List all available tags.

get_files_by_tag

Get files with a specific tag.

Parameters:

• tag (string, required): Tag name

get_file_metadata

Get metadata for a file.

Parameters:

• source (string, required): Source name
• file (string, required): File path

refresh_file_list

Force refresh file cache.

Parameters:

• source (string, required): Source name

stop_watching

Stop watching a source.

Parameters:

• source (string, required): Source name

Resources

Context files are exposed as MCP resources with URIs:

context://<source-name>/<file-path>

Example: context://project-docs/auth/oauth2.md

Resources include metadata:

• tags: Array of tags
• title: File title (from frontmatter)
• description: File description (from frontmatter)

GitHub Authentication

For private repositories, create a GitHub Personal Access Token (PAT):

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate new token with repo scope
3. Use the token when adding a GitHub source

Security Note: Store tokens securely. Consider using environment variables:

{
  "mcpServers": {
    "context-files": {
      "command": "node",
      "args": ["/path/to/index.ts"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Then modify the service to read from process.env.GITHUB_TOKEN.

Use Cases

Documentation Assistant

Keep all project documentation in context for accurate answers:

"Using the API guidelines and authentication docs, help me implement a new endpoint"

Coding Standards Enforcement

Reference style guides and best practices:

"Review this code against our coding standards in 'standards/typescript.md'"

Knowledge Base

Build a searchable knowledge base:

"Search for 'deployment pipeline' across all documentation"

Multi-Project Context

Manage contexts for multiple projects:

Add local source 'project-a-docs' from /projects/a/docs
Add local source 'project-b-docs' from /projects/b/docs

Team Collaboration

Share context via GitHub:

Add GitHub source 'team-kb' from owner 'company' repo 'knowledge-base' path 'context'

Troubleshooting

Files Not Appearing

1. Check file extensions: Only .md, .txt, .context, and .mdx files are indexed
2. Verify path: Ensure the path is absolute and accessible
3. Refresh cache: Use refresh_file_list to force update

File Watching Not Working

1. Local sources only: File watching only works for local directories
2. Enable watching: Ensure watch: true when adding source
3. Check permissions: Verify read access to the directory

GitHub Connection Issues

1. Check token: Ensure PAT has repo scope
2. Verify repository: Confirm owner and repo names
3. Branch name: Default is "main", specify if different
4. Rate limits: GitHub API has rate limits; consider caching

Search Not Finding Files

1. Refresh source: Run refresh_file_list to update indexes
2. Check tags: Ensure files have proper frontmatter
3. Case sensitivity: Searches are case-insensitive but check spelling

Performance Tips

• Enable caching: File lists and metadata are cached automatically
• Use file watching: Avoid manual refreshes with automatic updates
• Tag organization: Well-tagged files improve search performance
• Limit scope: Search specific sources when possible
• GitHub rate limits: Cache aggressively for GitHub sources

Contributing

Contributions are welcome! Areas for improvement:

• Additional metadata extraction
• Custom file type support
• Advanced search operators
• Workspace integration
• Export/import configurations

License

MIT License - feel free to use and modify as needed.

Support

For issues and questions:

• Check the troubleshooting section
• Review Claude's MCP documentation: https://docs.claude.com
• File issues on your repository

Version History

v2.0.0

• Added file watching with chokidar
• Implemented tag indexing and categorization
• Added full-text search with relevance ranking
• Metadata extraction from frontmatter
• Enhanced error handling

v1.0.0

• Initial release
• Local and GitHub source support
• Basic file reading
• MCP tools and resources integration