使用说明

Scout MCP:面向Go开发者的MCP服务器

Scout MCP是一个全面的模型上下文协议（MCP）服务器，它为Go开发人员提供了与Claude一起使用的功能，包括通过stdio传输的文件访问和操作功能。

Go开发人员的主要突出功能是向 Go文档注释标准以便可以指示Claude添加文档来解决每个异常。

使用显式目录白名单、基于会话的指令执行和高级文件操作（包括基于AST的编辑）构建。

特性

基于会话的指令执行：所有交互都始于全面的说明和编码指南
显式目录白名单：只能访问指定的目录
全面的文件操作：20个用于读取、写入、编辑和分析文件的工具
- 会话管理: start_session 该工具提供指令和会话令牌
- 高效的文件读取: read_files 该工具可以在一次调用中读取多个文件/目录
- 基本操作：创建、更新、删除文件和搜索目录
- 高级编辑：基于行的操作、模式替换、基于AST的编辑
- 语言意识：Go、Python、JavaScript等的语法感知编辑
- 分析工具：文件验证、内容分析和结构检查
用户审批系统：写入操作需要用户明确确认并进行风险评估
安全：具有路径验证、会话管理和审批工作流的多层安全
stdio运输：通过子流程与Claude Desktop直接集成

快速开始

# Clone and build
git clone your-repo/scout-mcp
cd scout-mcp
make build

# Show help
./bin/scout help

# Create default config with allowed directory
./bin/scout init ~/Code

# Start MCP server with config file paths
./bin/scout mcp

# Or start with additional paths
./bin/scout mcp ~/MyProjects

# Or use only a specific path (ignore config)
./bin/scout mcp --only /tmp/safe-dir

# Session management
./bin/scout session new      # Create new session
./bin/scout session list     # List active sessions
./bin/scout session clear all  # Clear all sessions

# Tool operations
./bin/scout tool list        # List available tools

文档

Claude桌面集成 -将Scout MCP连接到克劳德桌面
配置指南 -本地配置选项
api参考 -可用工具及其参数
故障排除 -常见问题和解决方案

Claude桌面集成

Scout MCP使用stdio传输与Claude Desktop直接集成。这是不通过Claude的web界面配置，但通过Claude Desktop的配置文件。

设置步骤

1.构建Scout MCP

cd /path/to/scout-mcp
make build
# Binary will be created as ./bin/scout

2.查找Claude桌面配置文件

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%/Claude/claude_desktop_config.json

3.配置Scout MCP服务器

编辑（或创建）Claude Desktop配置文件：

{
  "mcpServers": {
    "scout-mcp": {
      "command": "/absolute/path/to/scout-mcp/bin/scout",
      "args": ["mcp", "/Users/yourusername/Projects"]
    }
  }
}

仅模式的替代方案：

{
  "mcpServers": {
    "scout-mcp": {
      "command": "/absolute/path/to/scout-mcp/bin/scout",
      "args": ["mcp", "--only", "/Users/yourusername/Projects"]
    }
  }
}

配置说明：

使用 绝对路径 对于命令和参数
这 args 数组应包含您允许的目录
Scout MCP作为Claude Desktop的子进程运行
无需URL或网络配置

4.重新启动克劳德桌面

完全退出并重新启动Claude Desktop以使更改生效。

5.测试集成

在新的克劳德谈话中，你必须 从会话设置开始:

start_session

然后，您可以使用以下命令：

“读取mcptools目录中的所有Go文件”
“显示主要文件：main.go、README.md和./mcptools中的所有文件”
“在我当前的项目中搜索包含'tool'的.go文件”
“递归列出所有README文件”

多目录示例

{
  "mcpServers": {
    "scout-mcp": {
      "command": "/Users/mike/Projects/scout-mcp/bin/scout",
      "args": [
        "mcp",
        "/Users/mike/Projects",
        "/Users/mike/Documents/Code"
      ]
    }
  }
}

集成故障排除

Claude中没有可用的工具：

验证二进制路径是否正确且可执行
检查是否存在允许的目录
配置更改后重新启动Claude Desktop
检查Claude Desktop日志中的错误消息

“拒绝访问”错误：

确保请求的路径在允许的目录内
在配置中使用绝对路径
验证目录权限

“会话令牌无效”错误：

呼叫 start_session 首先获得有效令牌
会话令牌在24小时后过期
服务器重新启动时，令牌无效

命令行用法

Scout MCP通过命令行参数提供灵活的路径管理：

基本命令：

scout help -通过示例显示所有命令的帮助
scout mcp <path> -将路径添加到配置文件路径并启动服务器
scout mcp --only <path> -仅使用指定的路径（忽略配置文件）
scout init -创建空配置文件（需要手动编辑）
scout init <path> -使用自定义初始路径创建配置
scout mcp -仅使用配置文件路径启动服务器

示例：

# Show help with examples
scout help

# Start with ~/Projects (from config) + ~/MyCode (from command line)
scout mcp ~/MyCode

# Use only /tmp/safe-dir, ignore any config file
scout mcp --only /tmp/safe-dir

# Create config with ~/Development as initial directory
scout init ~/Development

# Start with just config file paths
scout mcp

错误处理：

无参数运行显示了示例和用法的全面帮助
未知命令显示有用的错误消息和使用指南 scout help
在启动之前，所有路径都被验证为存在并且是目录
清晰的错误消息解释了可用的选项
之间的帮助输出一致 scout 和 scout help 命令

配置

配置文件

配置文件在以下位置自动创建 ~/.config/scout-mcp/scout-mcp.json:

{
  "allowed_paths": [
    "/home/yourusername/Projects"
  ],
  "port": "8754",
  "allowed_origins": [
    "https://claude.ai",
    "https://*.anthropic.com"
  ]
}

路径管理

配置文件路径：配置文件中指定的持久目录 命令行路径：为单个会话添加临时路径 组合模式 （默认）：命令行路径将添加到配置文件路径中 仅模式 (--only 标志）：仅使用命令行路径，忽略配置文件

安全说明：

仅添加您希望Claude访问的目录
使用绝对路径清晰明了
允许路径的子目录可以自动访问
所有路径在启动时都经过验证

使用示例

一旦连接到Claude Desktop，您 必须开始每一次谈话 与：

start_session

这为您提供了会话令牌和全面的说明。然后，您可以使用以下命令：

"Read these files: main.go, README.md, and all .go files in ./mcptools"
"Search for all .go files containing 'tool' recursively"
"Show me all configuration files in my project"
"Read the entire ./test directory to understand the test structure"

API工具

Scout MCP为Claude提供了20个全面的工具：

会话管理

start_session: ⭐ 从这里开始 -创建会话令牌并获取全面的说明（不需要会话令牌）

增强的文件读取

read_files：使用筛选选项高效读取多个文件和/或目录
search_files：在允许的目录中按名称模式列出和搜索文件

基本文件操作（需要批准）

create_file：在允许的目录中创建新文件
update_file：替换整个文件内容(⚠️ 危险-使用粒度工具代替）
delete_files：删除文件或目录

精细编辑操作（需要批准）

update_file_lines：用行号范围替换文件中的特定行
delete_file_lines：从文件中删除特定行范围
insert_file_lines：在特定行号处插入内容
insert_at_pattern：在模式匹配之前/之后插入内容
replace_pattern：使用正则表达式支持查找和替换文本模式

语言感知操作（基于AST）

check_docs：查找所有没有一致性注释、顶部注释或README的types/funcs/var/consts/etc。
find_file_part：查找特定的语言结构（函数、类型等）
replace_file_part：使用语法感知解析替换语言构造（需要批准）
validate_files：验证源代码文件的语法

分析和系统工具

analyze_files：分析文件结构并提供见解
get_config：显示当前Scout MCP配置
tool_help：获取所有工具的详细文档
detect_current_project：通过分析Git存储库中最近的文件修改来检测最近活动的项目

审批制度

request_approval：请求用户批准风险操作
generate_approval_token：在用户确认后生成批准令牌

安全功能

多层安全模型

Scout MCP通过多种机制实现全面安全：

会话管理

需要会话令牌：所有工具（除 start_session)需要有效的会话令牌
24小时到期：会话令牌自动过期
服务器重启无效：服务器重新启动时令牌无效
指令交付：每节课都提供编码指南和工具文档

路径验证

所有文件访问请求都会根据白名单进行验证
绝对路径解析可防止目录遍历攻击
只允许目录（不允许单个文件）

用户审批系统

写入操作需要明确的用户确认 通过stdio提示
风险评估：操作分为低、中或高风险
操作预览：用户在批准之前确切地看到将要更改的内容
批准令牌：在用户确认安全操作执行后生成
交互式提示：清楚地描述每个操作将做什么

操作分类

读取操作：自动允许白名单目录中的文件
写入操作：要求用户批准并发出基于风险的警告
分析操作：安全的只读分析和验证工具

stdio安全

无网络暴露-仅通过Claude Desktop进行通信
进程隔离-作为范围有限的子进程运行
本地主机stdio通信不需要身份验证

访问日志记录

服务器在启动时记录所有允许的目录
记录了无效的访问尝试及其详细信息
记录审批请求和响应以进行审计跟踪

测试您的设置

使用Claude Desktop进行手动测试

配置Claude Desktop集成后：

开始新的对话 在克劳德桌面
先开始会话：呼叫 start_session 获取令牌和指令
测试基本阅读：“读取mcptools目录中的所有文件”
测试递归搜索：“在我的scout mcp项目中递归搜索.go文件”
测试多文件读取：“阅读这些文件：main.go、README.md”
测试模式匹配：“显示名称中包含'config'的所有文件”

本地开发测试

测试服务器并运行综合测试套件：

# Run the comprehensive test suite
./test/run_tests.sh

# Run individual Go tests
go test ./...

# Test the server standalone before Claude integration
./bin/scout mcp ~/Projects

# Test with manual JSON (in another terminal, pipe input)
echo '{"id":1,"method":"tools/list","params":{}}' | ./bin/scout mcp ~/Projects

集成测试

验证集成是否正常工作：

start_session
"Read all files in my mcptools directory"
"Search for .go files in my current project"
"Read main.go and README.md together"
"Find all package.json files recursively"

故障排除

命令行问题

“分析参数时出错：路径不存在”

验证路径是否存在： ls -la /your/path
使用绝对路径清晰明了
检查目录的权限

“未指定允许的目录”

跑 scout init 创建默认配置
或指定路径： scout mcp /your/project/path
检查配置文件是否存在： cat ~/.config/scout-mcp/scout-mcp.json

Claude桌面集成问题

Claude中未出现的工具：

验证claude_desktop_config.json中的二进制路径是否正确且绝对
检查二进制文件是否可执行： chmod +x /path/to/scout-mcp
配置更改后完全重新启动Claude Desktop
验证允许的目录是否存在并且可读

“拒绝访问：不允许路径”

检查请求的路径是否在允许的目录内
验证配置中的路径是否绝对存在
确保Claude Desktop配置参数与预期目录匹配

“会话令牌无效或过期”

呼叫 start_session 首先获得有效令牌
会话令牌在24小时后过期
服务器重新启动时，令牌无效
每次新的对话都应该从以下内容开始 start_session

服务器未启动：

手动测试二进制文件： ./bin/scout mcp ~/Projects
检查Go编译错误
验证是否已安装所有依赖项

连接问题

工具无响应：

检查Claude Desktop的开发人员控制台以获取错误消息
验证进程是否正在运行： ps aux | grep scout
首先以最小配置进行测试

配置参考

配置文件选项

文件位置: ~/.config/scout-mcp/scout-mcp.json

allowed_paths：Claude可以访问的目录路径数组
port：端口号（旧版-不用于stdio传输）
allowed_origins：CORS起源（遗留-不用于stdio传输）

Claude桌面配置

文件位置: ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）

command：侦察二进制的绝对路径（例如。， /path/to/scout-mcp/bin/scout)
args：以开头的数组 "mcp" 命令后跟允许的目录路径
服务器作为Claude Desktop的子进程运行，改进了I/O分离

环境考虑因素

确保运行Claude Desktop的用户对允许的目录具有读取权限
命令行路径未持久化到配置文件
使用绝对路径避免工作目录问题

建筑与发展

Scout MCP遵循“清晰路径”编码风格，具有全面的安全性和测试性：

基于会话的体系结构

所有工具都需要会话令牌（除了 start_session)
MCP服务器层的框架级会话验证
每节课都提供全面的指导

工具类别

会话管理：令牌创建和指令传递
文件读取：具有过滤功能的高效多文件读取
文件管理：创建、更新、删除操作并获得批准
精细编辑：基于线条和图案的编辑
语言意识：基于AST的语法感知操作解析
分析：文件验证和结构分析
系统：配置和帮助工具
批准：风险评估和审批工作流程

贡献

在贡献时，请遵循整个项目中使用的“清晰路径”编码风格：

使用 goto end 模式而不是早期回报
每个具有命名返回变量的函数有一个返回点
通过辅助函数实现最小嵌套
所有在第一个之前声明的变量 goto
无可变阴影

许可证

麻省理工学院

TODO（给我和克劳德的笔记）

添加通过环境变量、CLI开关和/或配置文件指定日志去向的功能。我希望它能很容易地说“在当前目录中”或 ./log 目录。

JSON模式

TODO:MCP工具的JSON模式支持

需求

核心实施

[]添加 Schema() map[string]any 工具界面方法
[]从现有JSON模式生成JSON模式 Properties 结构（不要重复定义）
[]返回MCP中的模式 list_tools 协议合规性响应

架构特性

[ ] 类型验证：字符串、数字、布尔值、数组、对象类型
[ ] 必需参数与可选参数：根据需要标记session_token和核心参数
[ ] 默认值：指定可选参数的默认值（例如，递归：false）
[ ] 参数说明：每个参数的人类可读描述
[ ] 数组项类型：指定数组元素的类型（例如，路径数组包含字符串）

工具特定架构要求

[ ] start_session：没有必需的参数，返回session_token
[ ] read_files：paths（必填字符串数组），session_token（必填字符串）
[ ] 搜索文件：path（必填字符串）、模式/扩展名（可选）、session_token（必填）
[ ] 文件编辑工具：文件路径+内容+会话令牌（都是必需的）
[ ] 除start_session之外的所有工具：session_token参数标记为必需

集成优势

[ ] 客户端验证：在发送到服务器之前验证参数
[ ] 自动完成：IDE和Claude Desktop可以建议参数
[ ] 文档：tool_help可以从模式生成参数文档
[ ] 错误消息：格式错误的请求有更好的验证错误

实施策略

[]从现有属性生成模式，而不是手工编码
[]保留Go原生属性供内部使用，MCP协议的架构
[]在现有单元测试旁边添加模式验证测试
[]确保与当前工具实现的向后兼容性

未来的考虑因素

[]如果工具参数发生变化，则进行架构版本控制
[]复杂的验证规则（例如，模式中的路径白名单验证）
[]条件参数（例如，递归仅对目录操作有效）

使用说明

Scout MCP:面向Go开发者的MCP服务器

特性

快速开始

文档

Claude桌面集成

设置步骤

1.构建Scout MCP

2.查找Claude桌面配置文件

3.配置Scout MCP服务器

4.重新启动克劳德桌面

5.测试集成

多目录示例

集成故障排除

命令行用法

配置

配置文件

路径管理

使用示例

API工具

会话管理

增强的文件读取

基本文件操作（需要批准）

精细编辑操作（需要批准）

语言感知操作（基于AST）

分析和系统工具

审批制度

安全功能

多层安全模型

会话管理

路径验证

用户审批系统

操作分类

stdio安全

访问日志记录

测试您的设置

使用Claude Desktop进行手动测试

本地开发测试

集成测试

故障排除

命令行问题

Claude桌面集成问题

连接问题

配置参考

配置文件选项

Claude桌面配置

环境考虑因素

建筑与发展

最近的改进

基于会话的体系结构

工具类别

贡献

许可证

TODO（给我和克劳德的笔记）

JSON模式

TODO:MCP工具的JSON模式支持

需求

核心实施

架构特性

工具特定架构要求

集成优势

实施策略

未来的考虑因素

相关 MCP

GitHub API服务器

Excel文件管理分析服务

Python解释器服务

React开发协议服务

内存银行管理协议

React开发协议服务