# onlinecybertools-mcp-server

MCP (Model Context Protocol) server that lets AI agents — Claude Code, Codex,
Cursor, Continue, etc. — use the
[Online Cyber Tools](https://onlinecybertools.com) catalogue as a set of
native MCP tools.

## What it exposes

- One MCP tool per documented MCP-compatible `/api/tools/{category}/{tool}`
  operation. `POST` tools use their JSON request-body schema; compatible
  `GET` tools use OpenAPI query/path parameters. Schemas are taken straight
  from the site's OpenAPI 3.1 spec at `/api/openapi.json`, so agents get
  per-tool argument validation. When the spec declares them, a tool also
  carries MCP `annotations` (`title` plus `readOnlyHint` /
  `destructiveHint` / `idempotentHint`, sourced from `x-mcp-annotations`)
  and an `outputSchema` (the inline `200` response object schema).
- A `search` meta-tool that performs the same keyword search humans use,
  backed by `GET /api/tools/search?q=...`.
- A `describe_tool` meta-tool that fetches the long page guidance, source
  links, page URL, API endpoint, and SEO description from
  `GET /api/mcp/tool-docs/{tool_id}`. It accepts either a menu ID such as
  `ping` or an MCP tool name such as `network_ping`.
- A `report_bug` meta-tool that files a structured bug report against
  `POST /api/agent/bug-report` (hard rate-limited).

Calls are proxied to the live HTTP API — no algorithm is re-implemented here.
That guarantees agents see whatever the deployed site does.
Generated tool descriptions are the operation's OpenAPI summary + description,
nothing else — no menu-ID prefix or `describe_tool` pointer (both read as
noise to a calling agent). The `describe_tool` meta-tool is still available
for agents that want the full page guidance on demand.

<!-- TOOLS:BEGIN (auto-generated by `php bin/console mcp:tools-doc`; do not edit by hand) -->
## Tools

This server exposes **279 tools** across 15 categories:
Encoding/Decoding, Binary/Text Conversion, Cryptography & Hashing, Web Dev Utilities, Text Utilities, OSINT Tools, Networking Tools, Security Tools, SEO Tools, Linux Tools, Date & Time, Math & Calculators, Data Tools, File Tools, Reverse Engineering.

- **Full list (this repo):** [`TOOLS.md`](./TOOLS.md) — every tool, grouped by category.
- **Live catalogue:** <https://onlinecybertools.com/#browse-the-full-inventory>
- **Machine-readable spec:** <https://onlinecybertools.com/api/openapi.json>
- **Pick a subset / build a config:** <https://onlinecybertools.com/integrations/mcp-plugin-builder>

This section and `TOOLS.md` are auto-generated from the live menu on
every release, so the count and list never drift.
<!-- TOOLS:END -->

## Quick start

The package is published on npm as
[`onlinecybertools-mcp-server`](https://www.npmjs.com/package/onlinecybertools-mcp-server),
so any MCP client can launch it with `npx -y onlinecybertools-mcp-server`
— no clone, no global install. The config snippets below work as-is and
expose the **full tool catalogue** by default.

Prefer a guided setup? Generate a ready-made Claude Code plugin or Codex
config block from the website's interactive builder:

  **<https://onlinecybertools.com/integrations/mcp-plugin-builder>**

The builder lets you pick a subset of tools and emits the matching
`OCTOOLS_TOOLS` filter for you (see [Configuration](#configuration)).

## Configuration

Configure via environment variables. All are optional.

| Variable                        | Default                                 | Purpose |
|---------------------------------|-----------------------------------------|---------|
| `OCTOOLS_BASE_URL`              | `https://onlinecybertools.com`          | Site to proxy requests to. |
| `OCTOOLS_TOOLS`                 | _(unset → all tools)_                   | Comma-separated menu IDs (`base64_encode,sha256,hash`) to restrict the exposed surface. **Leave unset to expose every tool** — the examples below omit it on purpose. |
| `OCTOOLS_STREAM_BYTE_CAP`       | `262144` (256 KiB)                      | Max bytes accumulated from a streamed (`x-mcp-compatible: stream-buffered`) endpoint. |
| `OCTOOLS_STREAM_TIME_CAP_MS`    | `30000` (30 s)                          | Max wall-clock time spent buffering a streamed endpoint. |

When `OCTOOLS_TOOLS` is set, the server appends `?tools=...` to the spec
fetch so the site returns a pre-filtered spec; the client also enforces the
filter as defense-in-depth.

## Running

### Inspector (manual smoke test)

```bash
npx @modelcontextprotocol/inspector npx -y onlinecybertools-mcp-server
```

Open the inspector URL, click **List Tools** — you should see `search`,
`describe_tool`, `report_bug`, plus one entry per compatible Symfony API
operation. With no `OCTOOLS_TOOLS` set, the full catalogue is listed.

To hack on the server locally instead, clone and run from source:

```bash
git clone https://github.com/Jambozx/onlinecybertools-mcp-server.git
cd onlinecybertools-mcp-server
npm install
npx @modelcontextprotocol/inspector node index.mjs
```

### Claude Code

Add to `~/.claude.json` (or your project's `.mcp.json`):

```json
{
  "mcpServers": {
    "octools": {
      "command": "npx",
      "args": ["-y", "onlinecybertools-mcp-server"]
    }
  }
}
```

This exposes every tool. To restrict the surface, add an `env` block with
`OCTOOLS_TOOLS`:

```json
{
  "mcpServers": {
    "octools": {
      "command": "npx",
      "args": ["-y", "onlinecybertools-mcp-server"],
      "env": {
        "OCTOOLS_TOOLS": "base64_encode,sha256,hash"
      }
    }
  }
}
```

### Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.octools]
command = "npx"
args = ["-y", "onlinecybertools-mcp-server"]
```

To restrict the surface, add an `env` line with `OCTOOLS_TOOLS`:

```toml
[mcp_servers.octools]
command = "npx"
args = ["-y", "onlinecybertools-mcp-server"]
env = { OCTOOLS_TOOLS = "base64_encode,sha256,hash" }
```

### Cursor / Continue / generic MCP client

Most clients accept the same `command`/`args`/`env` shape. Point them at
this package via `npx -y onlinecybertools-mcp-server`.

## Streaming endpoints

Endpoints tagged `x-mcp-compatible: stream-buffered` in the spec (currently
traceroute and proxy-test streams) are read to completion and returned as a
single JSON envelope of accumulated SSE events. GET stream endpoints send tool
arguments as query parameters; POST streams send JSON bodies. Hard caps:

- 256 KiB of buffered output (`OCTOOLS_STREAM_BYTE_CAP`)
- 30 s of wall-clock time (`OCTOOLS_STREAM_TIME_CAP_MS`)

Whichever cap fires first, the response envelope contains
`{ "truncated": true }` so the agent knows the output is partial.

Endpoints tagged `x-mcp-compatible: none` (multipart file uploads, etc.) are
**skipped at registration** — they will not appear in `tools/list`.

## Limitations

- Spec is fetched **once at startup**. If the site adds new endpoints, restart
  the server.
- stdio transport only; no HTTP server (avoids needing auth in front of a
  privileged endpoint).
- Published to npm as `onlinecybertools-mcp-server`
  (`npx -y onlinecybertools-mcp-server`). Installing straight from GitHub
  (`npx -y github:Jambozx/onlinecybertools-mcp-server`) still works for the
  bleeding edge.

## License

MIT.