io.github.marin1321/mcp-devtools
MCP server giving AI agents safe access to filesystem, databases, processes, and APIs.
Open source Open in the app JSON README (API)
About
MCP server giving AI agents safe access to filesystem, databases, processes, and APIs.
Details
- Kind
- MCP servers
- Topic
- Files & documents
- Publisher
- marin1321
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.1
- Stars
- 3
- Open pull requests
- 8
- Last push
- 2026-07-01T18:47:46Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:29
- Updated
- 2026-08-29 04:00:29
- Origin id
io.github.marin1321/mcp-devtools
README
# mcp-devtools
[](https://www.npmjs.com/package/@oscarmarin/mcp-devtools)
[](https://github.com/marin1321/mcp-devtools/actions/workflows/ci.yml)
[](./LICENSE)
[](https://nodejs.org/)
> **AI-native developer tools via [Model Context Protocol](https://spec.modelcontextprotocol.io).**
> A production-grade MCP server that gives AI agents (Claude, Cursor, Copilot, Continue, ...)
> safe, scoped access to your local development environment.
## Why
The MCP ecosystem is full of single-purpose tutorials and vendor-locked
adapters. There is no well-maintained, multi-tool, framework-agnostic,
production-quality MCP package for everyday developer tooling.
`mcp-devtools` fills that gap with **14 tools**, **3 MCP Resources**,
**4 MCP Prompts**, a **Plugin API**, **two transport modes** (stdio + HTTP
with auth), and an **audit log** — built on patterns refined in production
at [DailyBot](https://www.dailybot.com/).
## Quick start
### stdio (default)
```bash
npx @oscarmarin/mcp-devtools
```
Add it to **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"devtools": {
"command": "npx",
"args": ["-y", "@oscarmarin/mcp-devtools"]
}
}
}
```
Or **Cursor** (`~/.cursor/mcp.json`): same block.
### HTTP transport
Create a `mcp-devtools.json` in your project root:
```json
{
"transport": "http",
"port": 3333,
"auth": {
"token": "env:MCP_AUTH_TOKEN"
}
}
```
Then start the server:
```bash
npx @oscarmarin/mcp-devtools
```
The MCP endpoint will be available at `http://localhost:3333`.
## Tools
| Group | Tools |
| ---------- | ---------------------------------------------------------------------------- |
| Filesystem | `read_file`, `write_file`, `list_directory`, `search_files`, `get_file_info` |
| Database | `query_db`, `list_tables`, `describe_table` |
| Process | `run_command`, `read_logs`, `get_env`, `list_processes` |
| OpenAPI | `parse_openapi`, `call_api` |
Per-tool reference: [`docs/tools/`](./docs/tools/).
## MCP Resources
The server exposes read-only data via MCP Resources:
| URI | Description |
| ------------------------ | -------------------------------------------- |
| `devtools://tools` | Catalog of all registered tools with schemas |
| `devtools://server-info` | Server version, transport, scope, tool count |
## MCP Prompts
Curated prompt templates for common development workflows:
| Prompt | Description |
| ------------------- | ---------------------------------------------------------------- |
| `debug_error` | Systematically debug an error using mcp-devtools tools |
| `code_review` | Review a file for bugs, security issues, and code quality |
| `explore_codebase` | Explore and understand a project's structure and conventions |
| `refactor_function` | Refactor a function for readability, performance, or testability |
## Plugin API
Extend `mcp-devtools` with custom tools — no fork required.
**Config-based** (load at startup):
```json
{
"plugins": ["./my-tools.js", "@scope/mcp-plugin-foo"]
}
```
Each plugin module default-exports an array of tool definitions:
```typescript
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() },
}),
}),
];
```
## Configuration
Configuration is loaded by [`cosmiconfig`](https://github.com/cosmiconfig/cosmiconfig)
from `mcp-devtools.json`, `.mcp-devtoolsrc`, or the `mcpDevtools` key in
`package.json`. See [`mcp-devtools.example.json`](./mcp-devtools.example.json)
and [`docs/configuration.md`](./docs/configuration.md) for the full schema.
Zero-config is supported: running `npx @oscarmarin/mcp-devtools` with no config uses
schema defaults (RNF-05).
## Security
Four non-bypassable controls:
1. **Filesystem scope boundary.** Every path is resolved to an absolute and
compared against `config.scope`. Symlinks that escape scope throw
`SCOPE_VIOLATION`.
2. **Command allowlist.** `run_command` only executes binaries whose basename
is in `allowedCommands`. Invocation uses `spawn(file, args)` (no shell), so
shell-injection via the command argument is structurally impossible.
3. **Database read-only mode.** When `readOnly: true`, all SQL is parsed and
`INSERT/UPDATE/DELETE/DROP/CREATE/GRANT` are rejected. Queries run in
`BEGIN READ ONLY ... ROLLBACK` on PostgreSQL.
4. **HTTP Bearer auth.** When `auth.token` is configured, every HTTP request
must include `Authorization: Bearer <token>`. Comparison uses
`crypto.timingSafeEqual` to prevent timing attacks.
Additional safety measures:
- **Audit log.** Opt-in NDJSON log of every tool invocation with timing, sanitized
inputs, and result status.
- **Secret masking.** `get_env` automatically masks values matching common
secret patterns (`SECRET`, `TOKEN`, `PASSWORD`, `KEY`, etc.).
- **OpenAPI host restriction.** `call_api` only sends requests to hosts listed
in the spec's `servers` array.
- **Output capping.** All tools cap their output to prevent context flooding
(100KB for commands, 1MB for files, 200 rows for queries).
## Contributing
```bash
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 .
```
See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full workflow and
[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) for community guidelines.
## License
[MIT](./LICENSE) © Oscar Humberto Marin Molina —
[oscarmarindev.com](https://www.oscarmarindev.com)