aipulse
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`.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues