contextual (Yrstruely)

上下文文件MCP服务

一个强大的模型上下文协议（MCP）服务，用于管理来自本地目录和GitHub存储库的AI上下文文件。提供智能文件监视、基于标记的组织和全文搜索功能。

特性

✨ 双源支持

• 从本地文件系统目录读取
• 从GitHub存储库（公共和私有）获取

🔍 文件监视

• 自动检测文件更改（添加、修改、删除）
• 实时元数据和索引更新
• 高效监控，开销最小

🏷️ 智能标记和分类

• 从YAML frontmatter中提取标签
• 从内容中解析内联标签
• 基于标签的快速文件发现
• 元数据提取（标题、描述、标签）

🔎 全文检索

• 在所有上下文文件中搜索
• 基于相关性的排名
• 按标签和来源筛选
• 结果中的上下文片段

🚀 优化性能

• 智能缓存
• 增量更新
• 支持大型存储库

安装

先决条件

• Node.js 18+
• npm或纱线

设置

1. 克隆或下载服务：

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

1. 安装依赖项：

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

1. 创建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"
  }
}

1. 将服务代码另存为 index.ts

1. 使其可执行：

chmod +x index.ts

配置

适用于克劳德桌面

添加到您的 claude_desktop_config.json:

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

窗户： %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"]
    }
  }
}

克劳德代码

添加到MCP设置中：

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

窗户： %APPDATA%\claude-code\mcp_settings.json

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

用法

添加源

本地目录：

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

GitHub存储库：

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

管理上下文文件

列出来源：

Show me all configured sources

列出文件：

List all context files in 'project-docs'

读取文件：

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

读取多个文件：

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

搜索与发现

全文搜索：

Search for 'authentication flow' in my context files

使用标签过滤器搜索：

Search for 'database' in files tagged 'backend'

列出所有标签：

Show me all available tags

按标签查找：

Show me all context files tagged 'api'

获取元数据：

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

维护

刷新文件列表：

Refresh the file list for 'project-docs'

停止观看：

Stop watching 'project-docs' for changes

上下文文件格式

使用YAML frontmatter创建上下文文件以实现最佳组织：

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

支持格式

• 首页标签： tags: [tag1, tag2, tag3]
• 数组格式：

  tags:
    - tag1
    - tag2

• 内联标签： #tag1 #tag2 内容内

文件扩展名

该服务会自动检测这些文件类型：

• .md -Markdown文件
• .mdx -MDX文件
• .txt -纯文本文件
• .context -特定于上下文的文件

API 参考

工具

add_source

添加新的上下文文件源。

参数：

• name （string，必填）：源的标识符
• type （字符串，必填）： "local" 或 "github"
• path （string，必填）：目录路径或GitHub仓库路径
• watch （布尔值，可选）：启用文件监视（仅限本地）
• githubToken （字符串，可选）：GitHub PAT用于私有仓库
• owner （字符串，GitHub需要）：存储库所有者
• repo （字符串，GitHub需要）：存储库名称
• branch （字符串，可选）：分支名称（默认：“main”）

list_sources

列出所有已配置的源。

list_files

列出源中的文件。

参数：

• source （字符串，必填）：源名称

read_context_file

读取单个上下文文件。

参数：

• source （字符串，必填）：源名称
• file （字符串，必填）：文件路径

read_multiple_context_files

读取多个上下文文件。

参数：

• source （字符串，必填）：源名称
• files （array，必填）：文件路径数组

search_context_files

跨上下文文件搜索。

参数：

• query （字符串，必填）：搜索查询
• tags （数组，可选）：按标签筛选
• source （字符串，可选）：仅限于特定来源

list_tags

列出所有可用标签。

get_files_by_tag

获取具有特定标签的文件。

参数：

• tag （字符串，必填）：标记名称

get_file_metadata

获取文件的元数据。

参数：

• source （字符串，必填）：源名称
• file （字符串，必填）：文件路径

refresh_file_list

强制刷新文件缓存。

参数：

• source （字符串，必填）：源名称

stop_watching

停止观看来源。

参数：

• source （字符串，必填）：源名称

资源

上下文文件作为具有URI的MCP资源公开：

context:///

例子： context://project-docs/auth/oauth2.md

资源包括元数据：

• tags：标签数组
• title：文件标题（来自frontmatter）
• description：文件描述（来自frontmatter）

GitHub身份验证

对于私有存储库，创建GitHub个人访问令牌（PAT）：

1. 转到GitHub设置→ 开发者设置→ 个人访问令牌→ 代币（经典）
2. 使用生成新令牌 repo 范围
3. 添加GitHub源代码时使用令牌

安全说明： 安全地存储令牌。考虑使用环境变量：

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

然后修改服务以读取 process.env.GITHUB_TOKEN.

用例

文件助理

将所有项目文档放在上下文中以获得准确答案：

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

编码标准执行

参考风格指南和最佳实践：

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

知识库

构建一个可搜索的知识库：

"Search for 'deployment pipeline' across all documentation"

多项目背景

管理多个项目的上下文：

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

团队协作

通过GitHub分享上下文：

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

故障排除

文件未显示

1. 检查文件扩展名： 仅 .md, .txt, .context，以及 .mdx 文件已编入索引
2. 验证路径： 确保路径是绝对且可访问的
3. 刷新缓存： 使用 refresh_file_list 强制更新

文件监视不起作用

1. 仅限本地来源： 文件监视仅适用于本地目录
2. 启用观看： 确保 watch: true 添加源时
3. 检查权限： 验证对目录的读取权限

GitHub连接问题

1. 检查令牌： 确保PAT具有 repo 范围
2. 验证存储库： 确认所有者和回购名称
3. 分行名称： 默认值为“main”，如果不同，请指定
4. 费率限制： GitHub API有费率限制；考虑缓存

搜索未找到文件

1. 刷新源： 跑 refresh_file_list 更新索引
2. 检查标签： 确保文件有适当的封面
3. 病例敏感性： 搜索不区分大小写，但请检查拼写

性能提示

• 启用缓存： 文件列表和元数据会自动缓存
• 使用文件监视： 避免手动刷新和自动更新
• 标签组织： 标记良好的文件可提高搜索性能
• 限制范围： 尽可能搜索特定来源
• GitHub速率限制： 积极缓存GitHub源代码

贡献

欢迎投稿！需要改进的地方：

• 附加元数据提取
• 自定义文件类型支持
• 高级搜索运算符
• 工作空间集成
• 导出/导入配置

许可证

MIT许可证-可根据需要自由使用和修改。

支持

对于问题和疑问：

• 检查故障排除部分
• 查阅Claude的MCP文档：https://docs.claude.com
• 存储库中的文件问题

版本历史记录

v2.0.0版本

• 添加了使用chokidar观看文件
• 实现了标签索引和分类
• 添加了带有相关性排名的全文搜索
• 从frontmatter中提取元数据
• 增强的错误处理

v1.0.0

• 初始版本
• 本地和GitHub源代码支持
• 基本文件读取
• MCP工具和资源整合