Skip to main content
Glama
README.md
# aipulse

aipulse is a small local bridge to FalcoScan's hosted MCP
server, which tracks the AI product landscape: which
products exist in which markets, how those markets score
on opportunity, saturation and wrapper risk, and which
products have shut down or been acquired.

The bridge keeps no market data and computes no scores
of its own. It serves the upstream server's tool list
locally, exactly as captured from the live endpoint, and
forwards each tool call upstream, returning the result
untouched. The whole captured surface is read-only:
this rebuild adds no write capability.

## Tools

- `lookup_product` — look up an AI product by name
  (`name`), website (`url`), or both. Returns up to 5
  matches with market, operating / shut-down / acquired
  status (buyer, year and a source), opportunity,
  saturation and wrapper risk bands, pricing type, free
  tier, API availability, founding year, headquarters,
  website and a FalcoScan link. All arguments optional.
- `ai_graveyard` — products FalcoScan has verified as
  shut down or acquired, each with a published source.
  Optional filters: `year`, `buyer`, `market`. Up to
  25 rows per call, newest first.
- `list_markets` — every AI market FalcoScan scores,
  with its public averages (opportunity, saturation,
  wrapper share, heat), how many products in it are
  operating, and a link to its market page. No
  arguments.
- `market_overview` — one market in depth: operating
  product count, public averages, how many of its
  products shut down or were acquired, and its top 10
  operating products with bands. Required: `market`
  (a market name or slug).

## Configuration

- `FALCOSCAN_MCP_URL` (optional) — override the
  upstream endpoint. Defaults to
  `https://falcoscan.com/api/mcp`. (The override hook
  is this rebuild's own labelled reconstruction.)
- `FALCOSCAN_API_KEY` (optional) — when set, every
  upstream request carries an
  `Authorization: Bearer <key>` header. When it is not
  set, no auth header is sent. (This forwarding is
  also a labelled reconstruction; the original surface
  was captured keyless.)

### Forwarding mechanics

On the first tool call the client opens a streamable
HTTP session with the upstream: a JSON-RPC `initialize`
request (protocolVersion `2025-03-26`, clientInfo name
`aipulse`), then a `notifications/initialized`
notification, then the `tools/call` request carrying
the caller's arguments unchanged. When the upstream
answers `initialize` with an `Mcp-Session-Id` header,
that value rides on every later request of the session,
which is reused for the life of the process. Replies
may arrive as plain JSON or as server-sent events;
both are read.

Successful upstream results pass through verbatim,
including any `isError` flag the upstream sets.
Failures — a JSON-RPC error, a non-2xx status, an
unreadable response, or a request that cannot be
completed — come back as an `isError` result whose
text starts with `aipulse error:` (this rendering is
this rebuild's own labelled reconstruction).

## CLI

Each tool is also a subcommand taking one JSON argument
string (omit it for tools that take none):

```bash
npx @reneturcios/aipulse lookup_product '{"name":"Cursor"}'
npx @reneturcios/aipulse ai_graveyard '{"year":2025}'
npx @reneturcios/aipulse market_overview '{"market":"Healthcare"}'
npx @reneturcios/aipulse list_markets
npx @reneturcios/aipulse --version
```

Exit codes: `0` on success, `1` on an `isError`
result, `2` on a usage error.

## MCP server

```bash
npx -y @reneturcios/aipulse mcp
```

MCP client config:

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

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/aipulse
docker run --rm ghcr.io/cloudcorprecords/aipulse --version
```

The container's default command is `mcp`, so the first
form is a stdio MCP server; any other arguments reach
the CLI normally.

## Development

```bash
npm install
npm run build
npm test
npm run dev
```

The test suite runs entirely against a stubbed
JSON-RPC upstream — no live network calls.

## License

MIT — see `LICENSE`.