# ballpark

A forwarding client for the published Dribba MCP remote.
Dribba is a product studio; its remote MCP server exposes
public studio data — its services, its case studies, a
ballpark budget calculator, structured company facts, and
a contact-request tool. There is no installable package
for that remote, so ballpark gives it a local stdio MCP
server and a small CLI: `tools/list` is answered locally
from the verbatim live capture of the remote, and every
`tools/call` is forwarded to the remote over streamable
HTTP.

The upstream result passes through verbatim, including
`structuredContent` and any `isError` flag. Failures on
the way there or back are reported as an error result
whose text starts with `ballpark error: `.

## Upstream and the override

- Upstream: `https://dribba.com/mcp` (pinned).
- Override: set `DRIBBA_MCP_URL` to point the client at a
  different endpoint. This override is a reconstruction:
  no override is published for the remote-only original.
- The client handshake is `initialize` (protocol version
  `2025-03-26`, client `ballpark` / `0.1.0`), then
  `notifications/initialized`, then `tools/call`. When the
  upstream issues an `Mcp-Session-Id`, it is honoured on
  every later request. Responses may be plain JSON or an
  SSE stream.
- Argument validation is local: an unknown tool or
  malformed arguments fail before anything is forwarded.
  `submit_contact_request` is forwarded like the other
  tools; its captured description — which asks for
  explicit user confirmation of the exact name, email and
  message before calling — is served verbatim, and this
  rebuild adds no gating of its own.

## Install and run

```bash
npx -y @reneturcios/ballpark mcp          # stdio MCP server
npx -y @reneturcios/ballpark --version    # 0.1.0
npx -y @reneturcios/ballpark list_services '{"limit":3}'
npx -y @reneturcios/ballpark estimate_project '{"platforms":["ios","web"],"complexity":"standard"}'
npx -y @reneturcios/ballpark list_projects '{"industry":"fintech"}'
npx -y @reneturcios/ballpark company_facts '{"fields":["offices","distinctions"]}'
```

Each tool subcommand takes one JSON argument string and
prints the forwarded result. Exit codes: 0 on success,
1 on an error result, 2 on a usage or validation error.

## MCP client config

```json
{
  "mcpServers": {
    "ballpark": {
      "command": "npx",
      "args": ["-y", "@reneturcios/ballpark", "mcp"]
    }
  }
}
```

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/ballpark                    # stdio MCP server
docker run --rm ghcr.io/cloudcorprecords/ballpark --version        # CLI
```

## Tools

| Tool | What it does |
|---|---|
| `list_services` | List Dribba's services with a one-line summary and URL. |
| `estimate_project` | Ballpark budget and range for an app/product, mirroring dribba.com's public calculator. Minimum project budget is €30,000. Requires `platforms`. |
| `list_projects` | List Dribba's case studies (slug, title, industry). |
| `company_facts` | Structured facts about Dribba: positioning, offices, team, distinctions, clients. |
| `submit_contact_request` | Submit a real project inquiry to Dribba on behalf of the user. This sends an email and creates a lead — ONLY call it after the user has explicitly confirmed the exact name, email and message to be sent. Dribba replies within 1h. Rate-limited per client. |

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source
```

## License

MIT — Copyright (c) 2026 Rene Turcios.