Go MCP File Context Server

go-mcp文件上下文服务器

A Go port MCP文件上下文服务器 -模型上下文协议（MCP）服务器，其向大型语言模型（LLM）提供文件系统上下文。

特性

• 文件读取操作

- 使用元数据读取文件和目录内容 - 列出包含详细元数据的文件 - 递归目录遍历 - 文件类型筛选 - 批量文件检索 - 文件夹结构树生成

• 文件写入操作

- 创建新文件或覆盖现有文件 - 创建目录（包括嵌套路径） - 复制文件和目录 - 移动/重命名文件和目录 - 删除文件和目录 - 查找和替换文本（支持正则表达式）

• 代码分析

- 圈复杂度计算 - 依赖/导入提取 - 代码大纲生成（类、函数、导入） - 质量指标： - 重复行检测 - 长线检测（>100个字符） - 复杂功能识别 - 行数（总计、非空、注释）

• 智能缓存

- LRU（最近最少使用）缓存策略 - 可配置TTL（生存时间） - 缓存统计数据和性能指标

• 高级搜索

- 正则表达式模式匹配 - 具有可配置周围线条的上下文感知结果 - 文件类型筛选 - 多模式搜索支持

• 综合录井

- 文件访问日志记录（文件名和字节，从不记录内容） - 详细的启动信息 - 可配置的日志级别 - 自动创建日志目录

安装

下载预构建的二进制文件

从以下网址下载适用于您平台的二进制文件 发布 页面：

从源代码构建

# Clone the repository
git clone https://github.com/JeremyProffitt/go-mcp-file-context-server.git
cd go-mcp-file-context-server

# Build
go build -o go-mcp-file-context-server .

# Run
./go-mcp-file-context-server

配置

命令行选项

Usage: go-mcp-file-context-server [OPTIONS]

Options:
  -root-dir 
   Root directories to restrict file access (comma-separated)
                      Default: no restriction (full filesystem access)

  -blocked-patterns 

                      Patterns to block access to (comma-separated globs)
                      Default: .aws/*,.env,.mcp_env

  -allowed-patterns 

                      Patterns to allow (exceptions to blocked patterns)
                      Default: .aws/terraform,.aws/terraform/*,.aws/terraform/**

  -log-dir 
     Directory for log files
                      Default: ~/go-mcp-file-context-server/logs

  -log-level   Log level: off, error, warn, info, access, debug
                      Default: info

  -version            Show version information

  -help               Show help message

环境变量

笔记：

• 设置 MCP_BLOCKED_PATTERNS 为空字符串将禁用所有文件阻止。
• 允许的模式优先于被阻止的模式（例如。， .aws/terraform/* 即使可以访问 .aws/* 被封锁）。

配置优先

配置值按以下顺序解析（第一场比赛获胜）：

1. 命令行标志
2. 环境变量
3. 默认值

日志级别

安全说明： 日志永远不会捕获实际的文件内容。只记录文件名、路径和字节数。

默认设置

默认忽略模式

在文件操作过程中会自动忽略以下模式：

.git, node_modules, .vscode, .idea, __pycache__, .DS_Store,
*.pyc, .env, dist, build, coverage, .next, .nuxt, vendor, .cache

MCP服务器设置

克劳德桌面版

添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

基本设置（仅限于项目目录）：

{
  "mcpServers": {
    "file-context": {
      "command": "/path/to/go-mcp-file-context-server",
      "args": [
        "-root-dir", "/Users/username/projects/myproject",
        "-log-level", "access"
      ]
    }
  }
}

对于环境变量：

{
  "mcpServers": {
    "file-context": {
      "command": "/path/to/go-mcp-file-context-server",
      "env": {
        "MCP_ROOT_DIR": "/Users/username/projects,/Users/username/work",
        "MCP_BLOCKED_PATTERNS": ".aws/*,.env,.mcp_env,secrets/*",
        "MCP_ALLOWED_PATTERNS": ".aws/terraform,.aws/terraform/*,.aws/terraform/**",
        "MCP_LOG_DIR": "/var/log/mcp-file-context",
        "MCP_LOG_LEVEL": "debug"
      }
    }
  }
}

Windows示例：

{
  "mcpServers": {
    "file-context": {
      "command": "C:\\path\\to\\go-mcp-file-context-server-windows-amd64.exe",
      "args": [
        "-root-dir", "C:\\Users\\username\\projects\\myproject",
        "-log-level", "info"
      ]
    }
  }
}

完全文件系统访问（无限制）：

{
  "mcpServers": {
    "file-context": {
      "command": "/path/to/go-mcp-file-context-server",
      "args": ["-log-level", "access"]
    }
  }
}

带Claude扩展名的VS代码

添加到您的VS代码设置(settings.json):

{
  "claude.mcpServers": {
    "file-context": {
      "command": "/path/to/go-mcp-file-context-server",
      "args": [
        "-root-dir", "/path/to/project",
        "-log-level", "access"
      ]
    }
  }
}

或者在VS Code工作区设置中(.vscode/settings.json)具有工作区相对路径：

{
  "claude.mcpServers": {
    "file-context": {
      "command": "${workspaceFolder}/bin/go-mcp-file-context-server",
      "args": ["-log-level", "debug"],
      "env": {
        "MCP_ROOT_DIR": "${workspaceFolder}",
        "MCP_LOG_DIR": "${workspaceFolder}/logs"
      }
    }
  }
}

克劳德代码CLI

对于使用Claude Code CLI的本地工作区配置，请添加 .claude/mcp.json 将文件保存到项目根目录：

Windows示例：

{
  "mcpServers": {
    "file-context": {
      "command": "${workspaceFolder}/go-mcp-file-context-server.exe",
      "args": [
        "-root-dir", "${workspaceFolder}",
        "-log-dir", "${workspaceFolder}\\logs",
        "-log-level", "debug"
      ]
    }
  }
}

macOS/Linux示例：

{
  "mcpServers": {
    "file-context": {
      "command": "${workspaceFolder}/go-mcp-file-context-server",
      "args": [
        "-root-dir", "${workspaceFolder}",
        "-log-dir", "${workspaceFolder}/logs",
        "-log-level", "debug"
      ]
    }
  }
}

Continue.dev

注： MCP工具只能用于 代理模式 在Continue.dev中。请参阅 继续.md 获取详细的集成指南。

在中添加一个YAML文件 .continue/mcpServers/ 在您的工作区根目录：

例子： .continue/mcpServers/file-context.yaml

name: File Context Server
version: 0.0.1
schema: v1
mcpServers:
  - name: file-context
    command: /path/to/go-mcp-file-context-server
    args:
      - "-root-dir"
      - "/home/username/projects/myproject"
      - "-log-level"
      - "access"

Windows示例：

name: File Context Server
version: 0.0.1
schema: v1
mcpServers:
  - name: file-context
    command: C:/path/to/go-mcp-file-context-server.exe
    args:
      - "-root-dir"
      - "C:/Users/username/projects/myproject"
      - "-log-level"
      - "info"

全局配置

VS代码扩展名： ~/.continue/config.yaml

name: Local Config
version: 1.0.0
schema: v1

models: []

mcpServers:
  - name: file-context
    command: /path/to/go-mcp-file-context-server
    args:
      - "-root-dir"
      - "/home/username/projects"
      - "-log-level"
      - "debug"

CLI： ~/.continue/continue.yaml

mcpServers:
  - name: file-context
    command: /path/to/go-mcp-file-context-server
    args:
      - "-root-dir"
      - "/home/username/projects"
      - "-log-level"
      - "debug"

项目本地配置

添加一个 .continuerc.yaml 将文件保存到项目根目录：

mcpServers:
  - name: file-context
    command: ./go-mcp-file-context-server
    args:
      - "-root-dir"
      - "."
      - "-log-dir"
      - "./logs"
      - "-log-level"
      - "debug"

注： 使用 -root-dir "." 限制对当前工作目录的访问。

工具参考

本节对所有可用工具进行了分类概述，以帮助LLM快速确定每个任务的正确工具。

工具类别

工具选择指南

何时使用 list_context_files 对比 read_context 对比 get_folder_structure:

文件操作决策流程图：

1. 需要了解项目布局吗？ -> get_folder_structure （最大深度：3-5）
2. 需要查找特定的文件类型吗？ -> list_context_files 随着 fileTypes 过滤器
3. 需要读取文件内容吗？ -> read_context 对于单个文件， getFiles 对于多个
4. 需要找到代码模式吗？ -> search_context 使用正则表达式模式
5. 需要了解代码结构吗？ -> generate_outline 用于类/函数/导入
6. 需要代码质量指标吗？ -> analyze_code 复杂性和问题

常见工作流

工作流程1：探索新的代码库

1. get_folder_structure(path: ".", maxDepth: 3)     # Understand layout
2. list_context_files(path: ".", recursive: true)   # See all files with sizes
3. read_context(path: "README.md")                  # Read documentation
4. generate_outline(path: "src/main.go")            # Understand entry point

工作流程2：查找并修复错误

1. search_context(pattern: "error|bug|TODO", path: "src/", contextLines: 3)
2. read_context(path: "src/problematic_file.go")
3. modify_file(path: "src/problematic_file.go", find: "buggy_code", replace: "fixed_code")

工作流程3：代码审查和分析

1. analyze_code(path: "src/", recursive: true)      # Get complexity metrics
2. generate_outline(path: "src/main.go")            # See code structure
3. search_context(pattern: "TODO|FIXME|HACK")       # Find tech debt

工作流程4：批量文件读取

1. list_context_files(path: "src/", fileTypes: ["go"])  # Get file list
2. getFiles(filePathList: [{"fileName": "src/a.go"}, {"fileName": "src/b.go"}])

工作流程5：大文件处理

1. get_chunk_count(path: "large_file.log")          # Check chunk count
2. read_context(path: "large_file.log", chunkNumber: 0)  # Read first chunk
3. read_context(path: "large_file.log", chunkNumber: 1)  # Read next chunk

______________________________________________________________________

可用工具

list_context_files

列出目录中包含详细元数据的文件。

{
  "path": "./src",
  "recursive": true,
  "includeHidden": false,
  "fileTypes": ["go", "ts", "py"]
}

read_context

使用元数据和缓存读取文件或目录内容。

{
  "path": "./src/main.go",
  "maxSize": 10485760,
  "encoding": "utf8",
  "recursive": true,
  "fileTypes": ["go"],
  "chunkNumber": 0
}

搜索文本

在带有上下文线的文件中搜索图案。

{
  "pattern": "func.*Handler",
  "path": "./src",
  "recursive": true,
  "fileTypes": ["go"],
  "contextLines": 3,
  "maxResults": 100
}

分析代码

分析代码文件的复杂性、依赖性和质量指标。

{
  "path": "./src",
  "recursive": true,
  "fileTypes": ["go", "ts"]
}

generate_大纲

生成显示类、函数和导入的代码大纲。

{
  "path": "./src/main.go"
}

cache_stats

返回缓存统计信息和性能指标。

{
  "detailed": true
}

get_chunk_count

获取文件或目录的块总数。

{
  "path": "./large_file.txt",
  "chunkSize": 65536
}

getFiles

一次批量检索多个文件。

{
  "filePathList": [
    {"fileName": "./src/main.go"},
    {"fileName": "./pkg/utils.go"}
  ]
}

get_folder_structure

返回文件夹结构的树表示形式。

{
  "path": "./src",
  "maxDepth": 5
}

write_file

创建新文件或用内容覆盖现有文件。

{
  "path": "./src/newfile.go",
  "content": "package main\n\nfunc main() {}\n"
}

create_directory

创建一个新目录（如果需要，包括父目录）。

{
  "path": "./src/components/new-feature"
}

copy_file

将文件或目录从源复制到目标。

{
  "source": "./src/template.go",
  "destination": "./src/newfile.go"
}

move_file

移动或重命名文件或目录。

{
  "source": "./src/oldname.go",
  "destination": "./src/newname.go"
}

删除文件

从文件系统中删除文件或目录。

{
  "path": "./src/deprecated.go",
  "recursive": false
}

对于有内容的目录，设置 recursive: true.

修改文件

查找并替换文件中的文本。支持正则表达式模式。

{
  "path": "./src/main.go",
  "find": "oldFunction",
  "replace": "newFunction",
  "all_occurrences": true,
  "regex": false
}

使用正则表达式：

{
  "path": "./src/main.go",
  "find": "func (\\w+)\\(\\)",
  "replace": "function $1()",
  "all_occurrences": true,
  "regex": true
}

代码分析支持的语言

• 去
• Types/JavaScript
• python
• Java
• 锈
• C/C++
• 红宝石
• PHP

全局环境文件

所有go-mcp服务器都支持从以下位置加载环境变量 ~/.mcp_env。这提供了一个配置凭据和设置的中心位置，在GUI应用程序不从继承shell环境变量的macOS上特别有用 .zshrc 或 .bashrc.

文件格式

创建 ~/.mcp_env 对于KEY=VALUE对：

# ~/.mcp_env - MCP Server Environment Variables

# File Context Server Configuration
MCP_ROOT_DIR=~/projects,~/work
MCP_BLOCKED_PATTERNS=.aws/*,.env,.mcp_env
MCP_ALLOWED_PATTERNS=.aws/terraform,.aws/terraform/*,.aws/terraform/**
MCP_LOG_DIR=~/mcp-logs
MCP_LOG_LEVEL=info

特性

• 以开头的行 # 被视为评论
• 空行被忽略
• 值可以用单引号或双引号括起来
• 现有环境变量不会被覆盖 （环境变量优先）
• 路径与 ~ 会自动扩展到您的主目录
• 可以用逗号分隔指定多个根目录
• 阻塞模式支持glob语法（例如。， .aws/*, secrets/**)
• 允许的模式会对被阻止的模式产生例外（例如，允许 .aws/terraform/* 同时阻塞 .aws/*)

路径扩展

支持所有与路径相关的设置 ~ 扩展：

MCP_ROOT_DIR=~/projects/my-app,~/work/other-project
MCP_LOG_DIR=~/logs/file-context

这在 ~/.mcp_env 文件、环境变量和命令行标志。

日志文件位置

默认情况下，日志文件存储在：

日志文件的命名格式如下： go-mcp-file-context-server-YYYY-MM-DD.log

当 MCP_LOG_DIR 已设置或 -log-dir 如果使用标志，日志会自动放置在以二进制文件命名的子文件夹中。这允许多个MCP服务器共享同一日志目录：

MCP_LOG_DIR=/var/log/mcp
  └── go-mcp-file-context-server/
      └── go-mcp-file-context-server-2025-01-15.log

日志输出示例

[2025-01-15T10:30:45.123Z] [INFO] ========================================
[2025-01-15T10:30:45.123Z] [INFO] SERVER STARTUP
[2025-01-15T10:30:45.123Z] [INFO] ========================================
[2025-01-15T10:30:45.123Z] [INFO] Application: go-mcp-file-context-server
[2025-01-15T10:30:45.123Z] [INFO] Version: 1.0.0
[2025-01-15T10:30:45.123Z] [INFO] Go Version: go1.21.0
[2025-01-15T10:30:45.123Z] [INFO] OS: darwin
[2025-01-15T10:30:45.124Z] [INFO] Architecture: arm64
[2025-01-15T10:30:45.124Z] [INFO] Log Level: ACCESS
[2025-01-15T10:30:45.200Z] [INFO] TOOL_CALL tool="read_context" args=[path]
[2025-01-15T10:30:45.205Z] [ACCESS] FILE_READ path="/Users/dev/project/main.go" bytes=4521

发展

为当前平台构建

go build -v .

为所有平台构建

# macOS Universal Binary (Intel + Apple Silicon)
GOOS=darwin GOARCH=arm64 go build -o bin/go-mcp-file-context-server-darwin-arm64 .
GOOS=darwin GOARCH=amd64 go build -o bin/go-mcp-file-context-server-darwin-amd64 .
lipo -create -output bin/go-mcp-file-context-server-darwin-universal \
  bin/go-mcp-file-context-server-darwin-arm64 \
  bin/go-mcp-file-context-server-darwin-amd64

# Linux
GOOS=linux GOARCH=amd64 go build -o bin/go-mcp-file-context-server-linux-amd64 .
GOOS=linux GOARCH=arm64 go build -o bin/go-mcp-file-context-server-linux-arm64 .

# Windows
GOOS=windows GOARCH=amd64 go build -o bin/go-mcp-file-context-server-windows-amd64.exe .

运行测试

go test -v ./...

构建脚本

为了方便起见，提供了一个构建脚本：

./build.sh

这将为中的所有平台创建二进制文件 bin/ 目录。

故障排除

未创建日志

1. 确保日志目录存在并且可写
2. 检查一下 -log-level 未设置为 off
3. 验证环境变量是否正确传递

服务器未启动

1. 检查端口冲突或权限问题
2. 验证二进制文件是否具有执行权限： chmod +x go-mcp-file-context-server
3. 奔跑 -log-level debug 有关详细的启动信息

文件未被读取

1. 检查文件权限
2. 验证路径是否正确（尽可能使用绝对路径）
3. 检查文件是否处于忽略模式(.git, node_modules等等）
4. 验证文件大小不超过 maxSize 参数

许可证

麻省理工学院

学分