mcp-devtools

mcp-devtools

通过 Model Context Protocol 提供 AI 原生开发者工具。 一个适用于生产环境的 MCP 服务，为 AI Agent（Claude、Cursor、Copilot、Continue 等） 提供安全且范围受限的本地开发环境访问权限。

为什么选择它

MCP 生态中充斥着单一用途的教程和受供应商锁定的适配器。目前还没有维护良好、支持多种工具、不依赖特定框架且适用于生产环境的 MCP 软件包，可满足日常开发工具需求。

mcp-devtools 填补了这一空白，提供 14 个工具、3 个 MCP 资源、 4 个 MCP 提示词、插件 API、两种传输模式（stdio + HTTP 身份验证）以及审计日志 — 基于在 DailyBot 生产环境中不断完善的实践构建。

快速开始

stdio（默认）

npx @oscarmarin/mcp-devtools

将其添加到 Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "devtools": {
      "command": "npx",
      "args": ["-y", "@oscarmarin/mcp-devtools"]
    }
  }
}

或添加到 Cursor（~/.cursor/mcp.json）：使用相同的配置块。

HTTP 传输

在项目根目录中创建 mcp-devtools.json：

{
  "transport": "http",
  "port": 3333,
  "auth": {
    "token": "env:MCP_AUTH_TOKEN"
  }
}

然后启动服务：

npx @oscarmarin/mcp-devtools

MCP 端点将在 http://localhost:3333 上可用。

工具

分组	工具
文件系统	read_file、write_file、list_directory、search_files、get_file_info
数据库	query_db、list_tables、describe_table
进程	run_command、read_logs、get_env、list_processes
OpenAPI	parse_openapi、call_api

各工具的参考文档：docs/tools/。

MCP 资源

该服务通过 MCP 资源公开只读数据：

URI	描述
devtools://tools	包含所有已注册工具及其架构的目录
devtools://server-info	服务版本、传输方式、范围和工具数量

MCP 提示词

为常见开发工作流精选的提示词模板：

提示词	描述
debug_error	使用 mcp-devtools 工具系统地调试错误
code_review	检查文件中的错误、安全问题和代码质量
explore_codebase	探索并了解项目的结构和约定
refactor_function	重构函数，以提升可读性、性能或可测试性

插件 API

通过自定义工具扩展 mcp-devtools，无需分叉项目。

基于配置（启动时加载）：

{
  "plugins": ["./my-tools.js", "@scope/mcp-plugin-foo"]
}

每个插件模块都默认导出一个工具定义数组：

import { defineTool } from "@oscarmarin/mcp-devtools";
import { z } from "zod";

export default [
  defineTool({
    name: "my_tool",
    description: "Does something useful",
    inputSchema: z.object({ input: z.string() }),
    handler: async (args, config) => ({
      ok: true,
      data: { result: args.input.toUpperCase() },
    }),
  }),
];

配置

配置由 cosmiconfig 从 mcp-devtools.json、.mcp-devtoolsrc 或 package.json 中的 mcpDevtools 键加载。完整架构请参阅 mcp-devtools.example.json 和 docs/configuration.md。

支持零配置：不提供配置运行 npx @oscarmarin/mcp-devtools 时，将使用架构默认值（RNF-05）。

安全

四项不可绕过的控制措施：

1. 文件系统范围边界。 每个路径都会解析为绝对路径，并与 config.scope 进行比较。逃出范围的符号链接会触发 SCOPE_VIOLATION。
2. 命令允许列表。 run_command 仅执行其基本名称在 allowedCommands 中的二进制文件。调用使用 spawn(file, args)（不使用 shell），因此在结构上不可能通过命令参数进行 shell 注入。
3. 数据库只读模式。 当 readOnly: true 时，所有 SQL 都会经过解析，并拒绝 INSERT/UPDATE/DELETE/DROP/CREATE/GRANT。在 PostgreSQL 上，查询会在 BEGIN READ ONLY ... ROLLBACK 中运行。
4. HTTP Bearer 身份验证。 配置 auth.token 后，每个 HTTP 请求都必须包含 Authorization: Bearer <token>。比较使用 crypto.timingSafeEqual，以防止时序攻击。

其他安全措施：

• 审计日志。 可选择启用 NDJSON 日志，记录每次工具调用的耗时、经过清理的输入和结果状态。
• 机密信息屏蔽。 get_env 会自动屏蔽符合常见机密信息模式（SECRET、TOKEN、PASSWORD、KEY 等）的值。
• OpenAPI 主机限制。 call_api 仅向规范的 servers 数组中列出的主机发送请求。
• 输出限制。 所有工具都会限制输出大小，防止上下文被大量内容填满（命令为 100KB，文件为 1MB，查询为 200 行）。

贡献

git clone https://github.com/marin1321/mcp-devtools.git
cd mcp-devtools
npm install
npm run dev       # tsup --watch
npm run test      # vitest
npm run typecheck # tsc --noEmit
npm run lint      # eslint .

完整工作流请参阅 CONTRIBUTING.md，社区准则请参阅 CODE_OF_CONDUCT.md。

许可证

MIT © Oscar Humberto Marin Molina — oscarmarindev.com