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

概述

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

核心功能

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

Integrations