ToolCargo: portfolio / demo edition

This is a portfolio/demo edition, not the production codebase. It contains a runnable selection of genuine ToolCargo connector code with offline fixtures. The hosted product is at toolcargo.com. Source-available for viewing only; see LICENSE. Not open source.

ToolCargo is a store of hosted Model Context Protocol (MCP) connectors that let AI assistants such as Claude and ChatGPT use real tools: website audits, analytics and ads platforms, research databases, package registries and more. Users connect once with an account key or OAuth and add the connectors they need.

What is in this demo

The connector modules, the SSRF-guarded fetcher, the HTML parser and audit checks, the public-API transport and their unit tests are taken from the production code. The demo adds a small MCP server, a local playground UI and an offline mode.

Related MCP server: ViromeChat MCP server

Architecture

MCP client (Claude, an IDE, the demo UI)
        │  MCP (stdio here; Streamable HTTP in production)
        ▼
McpServer ── register*(server)        connector registration + zod input schemas
        │
        ├── lookup.ts / tools.ts      validation, bounded output projection, source notes
        │
        ├── public-http.ts            fixed-origin JSON transport for key-free public APIs
        └── site-audit/safe-fetch.ts  SSRF guard (DNS-time IP checks, redirect re-checks, size caps)
                 │
                 ▼
        offline fixtures (default)  or  real public endpoints (TOOLCARGO_DEMO_MODE=live)

Design rules visible in the code:

• Validate first, then fetch. Every input is checked (DOI syntax, package names, year ranges, URL scheme/host/port) before any request; SSRF checks still run in offline mode.

• Bounded, projected output. Connectors return a fixed subset of fields with explicit caps and "missing metadata" lists, never raw upstream payloads, author emails or full text.

• Upstream text is untrusted data. Each result ends with a source note telling the assistant what the data is and is not.

• Read-only tools with MCP annotations (readOnlyHint, idempotentHint).

What production has that this demo leaves out: accounts and OAuth 2.1, API keys and scopes, plans, metering and rate limits, billing, saved audit history, scheduled page watches, the catalogue website and the dozens of other connectors.

Run it

Requires Node.js 22.19.0 or newer.

npm ci
npm test          # deterministic, offline
npm run build     # strict TypeScript compile check
npm run demo      # playground UI at http://127.0.0.1:3000
npm run mcp       # MCP server over stdio

Offline mode is the default: tools answer from synthetic fixtures in src/demo/fixtures.ts (for example, audit https://example.com/ or look up DOI 10.5555/demo.2024.001). To call the real public APIs instead:

TOOLCARGO_DEMO_MODE=live npm run demo

No API keys or accounts are needed in either mode. See .env.example.

Use it from an MCP client

{
  "mcpServers": {
    "toolcargo-demo": { "command": "npx", "args": ["tsx", "/path/to/toolcargo-demo/src/mcp/stdio.ts"] }
  }
}

Layout

src/lib/connectors/   genuine connector code (site-audit core, crossref, europe-pmc, pypi-packages)
src/lib/catalog/      connector/tool metadata types (subset)
src/lib/mcp/          demo stand-ins for the production metering wrappers
src/lib/audit-compare.ts  run-comparison helpers from the production audit history
src/demo/             offline mode and synthetic fixtures
src/mcp/              demo MCP server (stdio + in-memory client)
src/ui/               local playground UI
tests/                unit tests from production + an end-to-end MCP test

License

Copyright (c) 2026 Eclipse Agency. All rights reserved. Source-available for viewing and local evaluation only; see LICENSE and THIRD-PARTY-NOTICES.md. Security reports: SECURITY.md.