文件上下文 MCP（模型上下文处理器）

Name: File Context MCP
Author: compiledwithproblems

铁匠徽章

概述

文件上下文 MCP 是一款基于 TypeScript 的应用程序，它提供了一个 API，用于查询包含本地文件上下文的大型语言模型 (LLM)。它支持多个 LLM 提供程序（Ollama 和 Together.ai），并且可以处理各种文件类型以生成上下文感知的响应。

Related MCP server: MemGPT MCP Server

核心功能

1. 文件系统导航

动态文件和目录遍历
支持多种文件类型（ .txt 、 .md 、 .ts 、 .json等）
通过消毒进行安全路径处理

import path from 'path'; export const fileUtils = { isTextFile(filePath: string): boolean { const textExtensions = [ '.txt', '.md', '.js', '.ts', '.json', '.yaml', '.yml', '.html', '.css', '.csv', '.xml', '.log', '.env', '.jsx', '.tsx', '.py', '.java', '.cpp', '.c', '.h' ]; return textExtensions.includes(path.extname(filePath).toLowerCase()); },

2. 上下文处理

LLM 查询的智能上下文格式
上下文截断来处理大文件
用于目录查询的文件内容聚合

export const promptUtils = { formatContextPrompt(context: string, query: string): string { return ` You are an AI assistant analyzing the following content: ---BEGIN CONTEXT--- ${context} ---END CONTEXT--- Please respond to the following query: ${query} Base your response only on the information provided in the context above. `; }, truncateContext(context: string, maxLength: number = 4000): string { if (context.length <= maxLength) return context; // Try to truncate at a natural break point const truncated = context.slice(0, maxLength); const lastNewline = truncated.lastIndexOf('\n'); if (lastNewline > maxLength * 0.8) { return truncated.slice(0, lastNewline) + '\n... (truncated)'; } return truncated + '... (truncated)'; } };

3. 多模型支持

Ollama（本地）集成
Together.ai（云）集成
可扩展模型接口设计

export interface LLMResponse { text: string; model: string; error?: string; } export class ModelInterface { async queryOllama(prompt: string, context: string): Promise<LLMResponse> { try { const response = await axios.post(`${config.ollamaBaseUrl}/api/generate`, { model: config.modelName, prompt: this.formatPrompt(prompt, context), stream: false }); return { if (!response.data || !response.data.response) { throw new Error('Invalid response from Ollama'); } } catch (error) { return { text: response.data.response, model: 'ollama' }; } catch (error) { console.error('Ollama error:', error); return { text: '', model: 'ollama', error: error instanceof Error ? error.message : 'Unknown error' }; } } model: config.modelName, async queryTogether(prompt: string, context: string): Promise<LLMResponse> { try { const response = await axios.post( 'https://api.together.xyz/inference', { model: config.modelName, prompt: this.formatPrompt(prompt, context), max_tokens: 512, }, { headers: { Authorization: `Bearer ${config.togetherApiKey}` } } ); return { return { text: response.data.output.text, model: 'together' }; } catch (error) { return { text: '', model: 'together', error: error instanceof Error ? error.message : 'Unknown error' }; } } private formatPrompt(prompt: string, context: string): string { return `Context: ${context}\n\nQuestion: ${prompt}`; } }

建筑学

核心组件

服务器（server.ts）
- Express.js REST API 实现
- 使用 multer 处理文件上传/删除
- 请求验证和路由
- OpenAPI/Swagger 集成
文件系统工具（core/fileSystem.ts）
- 文件和目录操作
- 内容读取和解析
- 目录遍历
- 安全文件删除
- 文件操作的错误处理
模型接口（core/modelInterface.ts）
- 多个 LLM 提供商支持（Ollama、Together.ai）
- 响应格式和错误处理
- 可配置模型参数
- 统一查询接口
实用模块
- fileUtils ：文件类型检测、路径清理、大小格式化
- promptUtils ：上下文格式化、智能截断
- validators ：路径、查询和模型验证
- logger ：具有级别的结构化日志记录
配置（config/config.ts）
- 环境变量管理
- API 密钥和端点
- 模型配置
- 服务器设置
API 规范（resources/file-context-api.yml）
- OpenAPI 3.0 文档
- 请求/响应模式
- 端点文档
- 错误响应定义

API 端点

1. 列出文件

GET /api/files Query params: - path: string (optional, defaults to './') Response: - Array of FileInfo objects with file/directory details

2.上传文件

POST /api/files/upload Content-Type: multipart/form-data Body: - file: File (must be a text file, max 5MB) Response: { "message": "File uploaded successfully", "file": { "name": string, "size": string, "path": string } }

3.删除文件

DELETE /api/files/{filename} Params: - filename: string (name of file to delete) Response: { "message": "File deleted successfully" }

4. 使用上下文进行查询

POST /api/query Body: { "path": string, "query": string, "model": "ollama" | "together" } Response: { "text": string, "model": string, "error?: string }

设置和配置

环境变量

TOGETHER_API_KEY=your_api_key_here OLLAMA_BASE_URL=http://localhost:11434 MODEL_NAME=llama2 PORT=3001

安装

npm install

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 File Context MCP：

npx @smithery/cli@latest install @compiledwithproblems/file-context-mcp --client claude

运行应用程序

# Development npm run dev # Production npm run build npm start

工作原理

文件处理流程
- 请求接收 → 路径验证 → 文件读取 → 内容提取
- 目录处理包括递归文件读取
- 基于文件类型的内容过滤
- 文件上传需要验证其类型和大小
- 通过路径验证来安全删除文件
上下文处理
- 文件内容被聚合
- 上下文具有清晰的边界
- 大型上下文被智能截断
- 提示格式为 LLM 理解添加了结构
模型集成
- 不同 LLM 提供商的统一接口
- 错误处理和响应规范化
- 可配置模型参数

安全功能

路径清理
- 防止目录遍历攻击
- 路径验证和规范化
- 安全文件类型检查
文件上传安全
- 文件类型验证
- 文件大小限制（最大 5MB）
- 安全文件存储
- 安全文件删除
输入验证
- 查询内容验证
- 模型类型验证
- 路径结构验证
- 文件内容验证

支持的文件类型

该应用程序支持以下基于文本的文件类型：

文档： .txt 、 .md
代码文件： .js ， .ts ， .jsx ， .tsx ， .py ， .java ， .cpp ， .c ， .h
配置： .json ， .yaml ， .yml ， .env
Web 文件： .html 、 .css
数据文件： .csv 、 .xml 、 .log

在以下情况下强制执行文件类型验证：

文件上传
上下文处理
文件读取操作

最大文件大小：每个文件 5MB

错误处理

该应用程序实现了全面的错误处理：

文件系统错误
API 响应错误
无效输入错误
模型特定错误
文件上传/删除错误

发展

项目结构

file-context-mcp/ ├── src/ │ ├── server.ts # Main application server │ ├── core/ # Core functionality │ │ ├── fileSystem.ts # File operations handling │ │ └── modelInterface.ts # LLM provider integrations │ ├── utils/ # Utility functions │ │ ├── fileUtils.ts # File type & path utilities │ │ ├── promptUtils.ts # Prompt formatting │ │ ├── validators.ts # Input validation │ │ └── logger.ts # Application logging │ ├── config/ # Configuration │ │ └── config.ts # Environment & app config │ └── resources/ # API specifications │ └── file-context-api.yml # OpenAPI spec ├── storage/ # File storage directory │ ├── code-samples/ # Example code files │ └── notes/ # Documentation & notes ├── postman/ # API testing │ └── File-Context-MCP.postman_collection.json # Postman collection ├── dist/ # Compiled output └── node_modules/ # Dependencies

添加新功能

新的文件类型
- 为fileUtils.isTextFile()添加扩展
- 如果需要，实现特定的处理程序
新模型提供者
- 扩展ModelInterface类
- 将提供程序添加到validators.isValidModel()
- 实现特定于提供程序的错误处理

测试

邮差收藏

该项目包含一个 Postman 集合 ( postman/File-Context-MCP.postman_collection.json )，用于测试所有 API 端点。使用方法如下：

导入收藏集
- 打开 Postman
- 点击“导入”按钮
- 选择或拖动File-Context-MCP.postman_collection.json文件
可用请求
File-Context-MCP ├── List files │ └── GET http://localhost:3001/api/files?path=./storage ├── Query │ └── POST http://localhost:3001/api/query (single file analysis) ├── Analyze multiple files │ └── POST http://localhost:3001/api/query (directory analysis) └── File Upload └── POST http://localhost:3001/api/files/upload
测试文件操作
- List Files ：查看存储目录的内容
- 上传文件：使用带有键“文件”的表单数据并选择一个文本文件
- 查询文件：使用 LLM 分析单个文件内容
- 分析目录：使用 LLM 处理多个文件
示例查询
// Single file analysis { "path": "./storage/code-samples/example.ts", "query": "Explain what this TypeScript code does", "model": "ollama" } // Directory analysis { "path": "./storage", "query": "What types of files are in this directory and summarize their contents?", "model": "ollama" }
文件上传指南
- 使用“文件上传”请求
- 在 Body 选项卡中选择“form-data”
- 添加“文件”类型的键“文件”
- 选择支持的文本文件（请参阅支持的文件类型）
- 最大文件大小：5MB

手动测试

使用/storage中提供的测试文件
测试不同的文件类型和查询
验证模型响应和错误处理
测试文件大小限制和类型限制

环境设置

请确保：

让服务器运行（ npm run dev ）
配置环境变量
让 Ollama 在本地运行（适用于 Ollama 模型）
设置 Together.ai API 密钥（用于 Together 模型）

未来考虑

如何高效处理大文件
扩展支持的文件类型
优化上下文处理
添加对响应的流支持
实施速率限制和缓存

该项目展示了现代 TypeScript/Node.js 实践，重点关注模块化、类型安全性和错误处理，同时为 LLM 与基于文件的上下文交互提供了灵活的接口。

File Context MCP