# 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:**
```bash
mkdir context-file-mcp
cd context-file-mcp
```

2. **Install dependencies:**
```bash
npm install @modelcontextprotocol/sdk@^0.5.0 @octokit/rest@^20.0.0 chokidar@^3.5.3
```

3. **Create package.json:**
```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:**
```bash
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`

```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`

```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:

```markdown
---
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:**
  ```yaml
  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:

```json
{
  "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