文件夹MCP
   
将任何文件夹转换为安全的MCP工具服务器。
FolderMCP扫描包含Python、Types/JavaScript、OpenAPI规范的目录， shell脚本和文档（PDF、图像、CSV、Markdown），然后将其作为 MCP（模型上下文协议） 工具和资源。 它处理发现、内省、依赖关系管理、沙盒执行和 协议自动转换——无需SDK，无需包装器代码，无需维护清单。
为什么选择FolderMCP？
- 所有语言都没有样板。 将Python函数、TypeScript导出、OpenAPI规范或shell脚本放入文件夹中，它就变成了一个MCP工具。PDF、图像和CSV成为MCP资源。不需要SDK集成。
- 默认情况下是安全的。 每个工具都始于
pending默认情况下使用拒绝权限状态。执行被沙盒化，具有可配置的超时、输出限制和秘密编辑。 - NAS和共享驱动器兼容。 适用于SMB、NFS、Azure文件和云端存储。自动检测网络文件系统，并将共享配置与本地状态分离。
- 一个连接命令。
foldermcp connect在几秒钟内将您的工具连接到Claude Desktop、Claude Code、Cursor、VS Code或Windsurf。 - 生产就绪工作流程。 三种审查模式（开发、团队、生产）、结构化审计日志、Docker/Cloud Run部署和健康/指标端点。
快速开始
# 1. Install
go install github.com/gtm-k/foldermcp/cmd/foldermcp@latest
# 2. Initialize
foldermcp init ./my-tools
# 3. Review & approve
foldermcp review --approve-all
# 4. Connect to your AI client
foldermcp connect claude-desktop
# 5. Start serving
foldermcp serve支持格式
| 格式 | 扩展名 | 发现内容 | 示例 |
|---|---|---|---|
python .py | 带有类型提示的函数 | def query(sql: str) -> str | |
| Types/JS | .ts, .js, .mjs, .cjs | 导出函数 | export function analyze(data: string) |
| OpenAPI | .yaml, .json | API操作 | GET/POST/DELETE端点 |
| 壳牌 | .sh, .bash | 脚本包装器 | ./deploy.sh |
| 文件 | .pdf, .md, .txt, .csv | MCP资源 | AI代理的上下文文档 |
| 图片 | .png, .jpg, .svg | MCP资源 | 图表、截图 |
CLI 参考
| 命令 | 描述 | 关键标志 |
|---|---|---|
foldermcp init [path] | 将目录初始化为工作区 | --template （python、openapi、shell） |
foldermcp review | 审查和批准/禁用发现的工具 | --approve-all, --confirm, --disable, --mode, --dry-run |
foldermcp serve | 启动MCP服务器 | --transport （stdio、http）， --mode, --port, --watch, --profile |
foldermcp connect | 配置客户端（claude桌面、claude代码、游标、vscode、windsurf） | --snippet, --mode |
foldermcp catalog | 在表格中列出所有发现的工具 | --state, --risk, --type |
foldermcp status | 显示工具和依赖关系状态摘要 | --json |
foldermcp test [tool] | 通过在本地运行工具来测试它 | --all, --force, --params |
foldermcp diff | 显示重新扫描时会发生什么变化 | --json |
foldermcp doctor | 检查环境是否存在问题 | --fix |
foldermcp deploy | 生成部署工件（docker、cloudrun） | --dry-run |
foldermcp export a2a | 导出A2A代理卡.json | --name, --url, --version |
foldermcp logs | 查看审核日志 | --follow, --json |
foldermcp ui | Open Developer Studio仪表板 | --port （默认值为3001） |
foldermcp completion | 生成shell补全（bash、zsh、fish、powershell） |
所有命令都支持 --json 机器可读输出的全局标志。
NAS/共享驱动器支持
FolderMCP设计用于开箱即用的网络连接存储：
- 支持的文件系统： SMB、NFS、Azure文件、云端存储（Google Drive、OneDrive）。
- 自动检测： 在运行时检测网络文件系统类型并相应地调整行为。
- 拆分存储： 共享配置(
foldermcp.yaml工具元数据）存在于NAS上；本地状态（审计日志、缓存）存在于本地计算机上的每个用户。 - 共享审批： 工具批准状态存储在共享驱动器上，因此整个团队都可以看到相同的审查状态。
- 观看模式：
foldermcp serve --watch使用基于轮询的文件监视，它在inotify/FSEvents不可用的网络文件系统上可靠地工作。
HTTP端点（团队/生产模式）
跑步时 --transport http 在团队或生产模式下：
/healthz--健康检查终点/readyz--准备就绪检查端点/metrics--Prometheus兼容指标
支持API密钥身份验证和自签名TLS证书生成。
开发者工作室
foldermcp ui在以下位置打开本地web仪表板 localhost:3001 与：
- 带有状态、风险等级和描述的实时工具目录
- 具有过滤功能的审核日志查看器
- 服务器状态和健康监控
配置
所有设置均已生效 foldermcp.yaml 在工作空间根目录下。跑 foldermcp init 生成一个默认值。
version: 1
scan:
include: ["*.py", "*.ts", "*.js", "*.yaml", "*.yml", "*.sh"]
exclude: ["tests/**", "node_modules/**", ".git/**"]
tools:
# Per-tool overrides
# my_tool:
# state: "enabled"
# description: "Custom description"
# risk: "high"
dependencies:
python: [] # e.g., [requests, flask]
node: [] # e.g., [express, typescript]
tool_routing:
max_tools_per_context: 20
strategy: "profile"
profiles:
# read_only: [query_db, list_files]
# admin: [delete_records, deploy_to_prod]安全
FolderMCP遵循默认拒绝安全模型：
- 所有工具均从开始
pending状态，在调用之前必须明确批准。 - 执行在具有可配置超时和输出限制的隔离子流程中进行沙盒处理。
- 输出清理会自动对AWS密钥、GitHub令牌、API密钥和私钥进行编校。
- 每个工具的风险标签：
read_only,side_effects,destructive,network. - 结构化审计日志记录，每次调用都使用JSON轮换。
有关报告漏洞和完整安全模型的详细信息，请参阅 安全.md.
项目结构
cmd/foldermcp/ CLI entry point (15 commands)
internal/
audit/ Structured JSON audit logging with rotation
cache/ Content-addressed source file cache
config/ YAML configuration with schema versioning
deps/ Dependency manager (uv for Python, npm for JS)
export/ A2A agent-card.json export
introspect/ Tool introspectors (Python, TS/JS, OpenAPI, Shell, Resources)
lifecycle/ State transition validation
pythonrt/ Shared Python runtime detection
sandbox/ Sandboxed executor with rate limiting and path guard
server/ MCP server (stdio + HTTP), auth, TLS, health/metrics
state/ SQLite state store
studio/ Developer web dashboard
watcher/ Polling file watcher (NAS-compatible)
workspace/ NAS split-storage manager, FS detection, shared approvals
examples/ Sample projects (Python, OpenAPI, Shell)贡献
欢迎捐款。请打开一个问题来讨论非琐碎的更改 在提交pull请求之前。
- 分叉存储库。
- 从以下位置创建要素分支
main. - 添加新功能的测试。
- 跑
make test和make lint在提交之前。 - 打开一个包含更改清晰描述的拉取请求。
看 贡献.md 获取完整指南。