tenderscope-lite

# tenderscope-lite

A tiny [MCP](https://modelcontextprotocol.io) server that lets your AI agent search **open EU public tenders** live from the official [TED](https://ted.europa.eu) Search API.

- One tool: `search_tenders`
- Runs locally over stdio, no database, no account, no API key
- Returns structured cards (title, buyer, country, budget, deadline, link), not web pages
- Only tenders whose deadline is still in the future

Want Armenian tenders (ARMEPS) with budgets read from the invitation documents, watchlists, deadline alerts and a hosted API? That is the hosted [TenderScope](https://tenderscope.app) service (free plan included). This package is its open-source thin version.

## Install

Requires Node.js 22 or newer.

```bash
npx -y github:MarutMarutyan/tenderscope-lite
```

Or from a clone (the repository already contains the built `dist/`):

```bash
git clone https://github.com/MarutMarutyan/tenderscope-lite.git
node tenderscope-lite/dist/tenderscope-lite.mjs
```

## Connect to Claude Desktop

Open the config file (Settings, Developer, Edit Config) and add:

```json
{
  "mcpServers": {
    "tenderscope-lite": {
      "command": "npx",
      "args": ["-y", "github:MarutMarutyan/tenderscope-lite"]
    }
  }
}
```

Restart Claude Desktop, then ask: "Find open IT tenders in Germany with a deadline next month."

## Connect to Cursor

Add the same block to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "tenderscope-lite": {
      "command": "npx",
      "args": ["-y", "github:MarutMarutyan/tenderscope-lite"]
    }
  }
}
```

## Tool: `search_tenders`

| Argument | Type | Meaning |
|---|---|---|
| `q` | string | Keywords, e.g. `software development`. May be empty. |
| `countries` | string[] | Buyer countries, ISO 3166-1 alpha-2 (EU/EEA), e.g. `["DE","FR"]` |
| `cpv` | string[] | CPV code prefixes, e.g. `["72"]` for IT services |
| `days` | integer | Look at notices published in the last N days (1-90, default 30) |
| `limit` | integer | Cards to return (1-20, default 10) |

Response: `{ "results": [ { id, title, buyer, country, budget, currency, deadline, publishedAt, cpv, url } ] }`. An empty result comes with a `hint` on how to widen the query. Budget is a string (`"125000.00"`), dates are ISO 8601 UTC; either may be `null` when the notice does not state them.

## Notes

- Data comes straight from the TED Search API v3 (no HTML scraping). Be polite: every tool call is one request.
- Only notice metadata and links are returned, never document texts.

## Development

```bash
npm install
npm run build   # bundles into dist/tenderscope-lite.mjs
npm test        # tests with a stubbed fetch, no network
```

The TED notice parser in `src/vendor/` is shared with the hosted service and copied from its repository on every release; send fixes as issues or pull requests here and they are carried over.

## License

MIT