{
  "markdown": "# mcp-devtools\n\n[![npm version](https://img.shields.io/npm/v/@oscarmarin/mcp-devtools.svg?color=6366F1)](https://www.npmjs.com/package/@oscarmarin/mcp-devtools)\n[![CI](https://github.com/marin1321/mcp-devtools/actions/workflows/ci.yml/badge.svg)](https://github.com/marin1321/mcp-devtools/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)\n\n> **AI-native developer tools via [Model Context Protocol](https://spec.modelcontextprotocol.io).**\n> A production-grade MCP server that gives AI agents (Claude, Cursor, Copilot, Continue, ...)\n> safe, scoped access to your local development environment.\n\n## Why\n\nThe MCP ecosystem is full of single-purpose tutorials and vendor-locked\nadapters. There is no well-maintained, multi-tool, framework-agnostic,\nproduction-quality MCP package for everyday developer tooling.\n\n`mcp-devtools` fills that gap with **14 tools**, **3 MCP Resources**,\n**4 MCP Prompts**, a **Plugin API**, **two transport modes** (stdio + HTTP\nwith auth), and an **audit log** — built on patterns refined in production\nat [DailyBot](https://www.dailybot.com/).\n\n## Quick start\n\n### stdio (default)\n\n```bash\nnpx @oscarmarin/mcp-devtools\n```\n\nAdd it to **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"devtools\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@oscarmarin/mcp-devtools\"]\n    }\n  }\n}\n```\n\nOr **Cursor** (`~/.cursor/mcp.json`): same block.\n\n### HTTP transport\n\nCreate a `mcp-devtools.json` in your project root:\n\n```json\n{\n  \"transport\": \"http\",\n  \"port\": 3333,\n  \"auth\": {\n    \"token\": \"env:MCP_AUTH_TOKEN\"\n  }\n}\n```\n\nThen start the server:\n\n```bash\nnpx @oscarmarin/mcp-devtools\n```\n\nThe MCP endpoint will be available at `http://localhost:3333`.\n\n## Tools\n\n| Group      | Tools                                                                        |\n| ---------- | ---------------------------------------------------------------------------- |\n| Filesystem | `read_file`, `write_file`, `list_directory`, `search_files`, `get_file_info` |\n| Database   | `query_db`, `list_tables`, `describe_table`                                  |\n| Process    | `run_command`, `read_logs`, `get_env`, `list_processes`                      |\n| OpenAPI    | `parse_openapi`, `call_api`                                                  |\n\nPer-tool reference: [`docs/tools/`](./docs/tools/).\n\n## MCP Resources\n\nThe server exposes read-only data via MCP Resources:\n\n| URI                      | Description                                  |\n| ------------------------ | -------------------------------------------- |\n| `devtools://tools`       | Catalog of all registered tools with schemas |\n| `devtools://server-info` | Server version, transport, scope, tool count |\n\n## MCP Prompts\n\nCurated prompt templates for common development workflows:\n\n| Prompt              | Description                                                      |\n| ------------------- | ---------------------------------------------------------------- |\n| `debug_error`       | Systematically debug an error using mcp-devtools tools           |\n| `code_review`       | Review a file for bugs, security issues, and code quality        |\n| `explore_codebase`  | Explore and understand a project's structure and conventions     |\n| `refactor_function` | Refactor a function for readability, performance, or testability |\n\n## Plugin API\n\nExtend `mcp-devtools` with custom tools — no fork required.\n\n**Config-based** (load at startup):\n\n```json\n{\n  \"plugins\": [\"./my-tools.js\", \"@scope/mcp-plugin-foo\"]\n}\n```\n\nEach plugin module default-exports an array of tool definitions:\n\n```typescript\nimport { defineTool } from \"@oscarmarin/mcp-devtools\";\nimport { z } from \"zod\";\n\nexport default [\n  defineTool({\n    name: \"my_tool\",\n    description: \"Does something useful\",\n    inputSchema: z.object({ input: z.string() }),\n    handler: async (args, config) => ({\n      ok: true,\n      data: { result: args.input.toUpperCase() },\n    }),\n  }),\n];\n```\n\n## Configuration\n\nConfiguration is loaded by [`cosmiconfig`](https://github.com/cosmiconfig/cosmiconfig)\nfrom `mcp-devtools.json`, `.mcp-devtoolsrc`, or the `mcpDevtools` key in\n`package.json`. See [`mcp-devtools.example.json`](./mcp-devtools.example.json)\nand [`docs/configuration.md`](./docs/configuration.md) for the full schema.\n\nZero-config is supported: running `npx @oscarmarin/mcp-devtools` with no config uses\nschema defaults (RNF-05).\n\n## Security\n\nFour non-bypassable controls:\n\n1. **Filesystem scope boundary.** Every path is resolved to an absolute and\n   compared against `config.scope`. Symlinks that escape scope throw\n   `SCOPE_VIOLATION`.\n2. **Command allowlist.** `run_command` only executes binaries whose basename\n   is in `allowedCommands`. Invocation uses `spawn(file, args)` (no shell), so\n   shell-injection via the command argument is structurally impossible.\n3. **Database read-only mode.** When `readOnly: true`, all SQL is parsed and\n   `INSERT/UPDATE/DELETE/DROP/CREATE/GRANT` are rejected. Queries run in\n   `BEGIN READ ONLY ... ROLLBACK` on PostgreSQL.\n4. **HTTP Bearer auth.** When `auth.token` is configured, every HTTP request\n   must include `Authorization: Bearer <token>`. Comparison uses\n   `crypto.timingSafeEqual` to prevent timing attacks.\n\nAdditional safety measures:\n\n- **Audit log.** Opt-in NDJSON log of every tool invocation with timing, sanitized\n  inputs, and result status.\n- **Secret masking.** `get_env` automatically masks values matching common\n  secret patterns (`SECRET`, `TOKEN`, `PASSWORD`, `KEY`, etc.).\n- **OpenAPI host restriction.** `call_api` only sends requests to hosts listed\n  in the spec's `servers` array.\n- **Output capping.** All tools cap their output to prevent context flooding\n  (100KB for commands, 1MB for files, 200 rows for queries).\n\n## Contributing\n\n```bash\ngit clone https://github.com/marin1321/mcp-devtools.git\ncd mcp-devtools\nnpm install\nnpm run dev       # tsup --watch\nnpm run test      # vitest\nnpm run typecheck # tsc --noEmit\nnpm run lint      # eslint .\n```\n\nSee [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full workflow and\n[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) for community guidelines.\n\n## License\n\n[MIT](./LICENSE) &copy; Oscar Humberto Marin Molina &mdash;\n[oscarmarindev.com](https://www.oscarmarindev.com)\n",
  "bytes": 6455,
  "sha": "3699f95b19f14b799660cf8c916093bdd6fb9fb968042bb95629f5c08d8399fd",
  "repo_slug": "marin1321/mcp-devtools",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_marin1321_mcp_devtools_508afaf0/readme"
}