# Archimedes Market Catalog MCP

A production-ready, read-only Model Context Protocol server for discovering
engineering work and reusable assets on [Archimedes Market](https://archimedes.market).
It gives Claude, Cursor, Copilot-compatible MCP hosts, and other agents four
small typed tools:

| Tool | Purpose |
| --- | --- |
| `search_assets` | Search public engineering asset titles and summaries |
| `get_asset` | Fetch one asset's public metadata and description |
| `search_bounties` | Search the official no-auth bounty API with filters |
| `get_bounty` | Fetch requirements, deliverables, and acceptance tests |

The server has no write tools and accepts no user credentials. It reads only
Archimedes' public bounty API and the anonymous published-asset catalog used by
the Archimedes browser client.

## Requirements

- Node.js 20.18.1 or newer
- Network access to `https://archimedes.market`

## Install and run

```bash
npm install
npm run ci
npm start
```

`npm start` launches the verified stdio entry point after the TypeScript build.

## Claude Desktop

Add this server to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "archimedes-catalog": {
      "command": "node",
      "args": ["C:/path/to/archimedes-market-catalog-mcp/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop, then try:

> Find funded software bounties between $100 and $500. Inspect the most
> relevant result and summarize its required deliverables.

## Cursor

Create `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "archimedes-catalog": {
      "command": "node",
      "args": ["C:/path/to/archimedes-market-catalog-mcp/dist/index.js"]
    }
  }
}
```

The same stdio configuration works in any standards-compatible MCP host.

## Tool examples

`search_bounties`:

```json
{
  "query": "MCP",
  "category": "software",
  "funding_status": "funded",
  "min_price_cents": 10000,
  "max_price_cents": 50000,
  "limit": 10
}
```

`get_bounty`:

```json
{
  "id": "89c2e397-bf5d-47d5-af06-7c5b749d76d1"
}
```

`search_assets`:

```json
{
  "query": "Python",
  "limit": 10
}
```

`get_asset`:

```json
{
  "id": "1878153b-096a-486e-ac6b-7197346bdff2"
}
```

## Architecture

```text
MCP host
  └─ stdio transport
      └─ typed, read-only MCP tools
          ├─ /api/public/bounties
          ├─ /api/public/bounties/{id}
          └─ published assets (public read-only data service)
```

The current public JSON API exposes bounty search and detail records. The
asset tools use the same anonymous catalog endpoint as the public web
application, always constrain reads to `status=published`, and return metadata
only. They never download paid files or bypass access controls.

## Reliability and security

- strict UUID, pagination, price-range, and result-size validation;
- 15-second request timeout;
- 2 MB response cap;
- allowlisted Archimedes API origins and cross-origin request rejection;
- no redirects, user authentication, environment secrets, or write methods;
- MCP errors contain actionable HTTP/validation context.

## Testing

```bash
npm test
npm run test:live
```

The regular suite is deterministic. The opt-in live suite exercises all four
tools against published Archimedes records and is intended for release
verification.

## Cloud deployment

The included multi-stage `Dockerfile` builds a non-root runtime image. It can
run as a stdio worker in AWS ECS/Fargate, Azure Container Apps jobs, Google
Cloud Run jobs, or any agent runtime that launches MCP subprocesses. Hosted
MCP gateways can wrap the stdio process with their preferred authenticated
HTTP transport without changing the catalog client.

## License

MIT