qlows-mcp

# qlows MCP connector

Bring your live **qlows** RFP/bid deals — and the public tender corpus — into
Claude, Cursor, Windsurf, Cline, Zed, or any [Model Context
Protocol](https://modelcontextprotocol.io) client.

`qlows-mcp` is a tiny local connector. It runs on your machine as a stdio MCP
server and securely proxies tool calls to the qlows API
(`https://app.qlows.com`). It stores nothing but your token, contains no
backend logic, and is **read-only** — your AI can pull deal context, never
write back.

> **Quotes. Flows. Close.** qlows preps the bid; your AI drafts from real,
> grounded context.

---

## Quick start (≈ 1 minute)

```bash
# 1. Connect your account (opens the browser, you paste a token back)
npx @qlows/mcp login

# 2. Verify it works
npx @qlows/mcp test          # → prints the available tools

# 3. Print the snippet for your AI client
npx @qlows/mcp config
```

Then add qlows to your client (example: **Claude Desktop**,
`~/Library/Application Support/Claude/claude_desktop_config.json`):

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

Restart the client. If you didn't run `login`, pass the token instead:

```json
{
  "mcpServers": {
    "qlows": {
      "command": "npx",
      "args": ["-y", "@qlows/mcp"],
      "env": { "QLOWS_TOKEN": "qlw_live_…" }
    }
  }
}
```

You'll need a qlows account to mint a personal token (free tier works for
tender search). Sign up + mint at **https://app.qlows.com/mcp**.

---

## Try these prompts

After connecting, ask your AI:

1. *"Use the qlows MCP to list my open deals, then summarize the top 3 risks
   in the most urgent one."*
2. *"Search public tenders for Zero-Trust networking in the EU closing in the
   next 30 days, and give me the qlows link for each."*
3. *"Read the deal `<deal-id>` from qlows and draft the Technical Approach
   section, grounding every claim in the compliance items and our approved
   answers."*

---

## What you get

All tools are **read-only**. Personal-data tools need a personal token; the
tender tools also work on a free account.

| Tool | What it does |
|---|---|
| `list_deals` | Your RFP/bid deals (lightweight metadata) |
| `get_deal_snapshot` | Full deal snapshot — RFP summary + compliance + Q-routing + intelligence |
| `search_compliance_items` | Keyword search across compliance items |
| `get_q_routing_state` | Sections + questions + answers + assignment state |
| `get_intelligence_summary` | AI summary + tailoring detection |
| `list_questions` | Flat question list |
| `list_competitors` | Per-deal competitor analysis |
| `search_tenders` | Public tender corpus search (FTS + filters) |
| `search_tenders_for_my_company` | Personalised semantic tender search |
| `get_tender_detail` | Full enriched record for one tender |

The connector discovers tools live from the server, so new qlows tools appear
without updating this package.

---

## Commands

| Command | Description |
|---|---|
| `qlows-mcp` | Run the MCP server over stdio (how clients launch it) |
| `qlows-mcp login` | Sign in via browser and store a token in `~/.qlows/config.json` (0600) |
| `qlows-mcp test` | List available tools to verify your token |
| `qlows-mcp config` | Print config path + a client setup snippet |
| `qlows-mcp help` | Usage |

**Environment variables**

- `QLOWS_TOKEN` — API token (overrides the stored one).
- `QLOWS_BASE_URL` — defaults to `https://app.qlows.com`; point at
  `http://localhost:3000` for local testing.

---

## How it works

```
MCP client (Claude/Cursor)  ⇄  qlows-mcp (stdio, local)  ⇄  https://app.qlows.com/api/mcp/<token>/rpc
```

The connector is a transparent JSON-RPC proxy. It does not implement tools — it
forwards `initialize`, `tools/list`, `tools/call`, and `resources/*` to the
qlows server and relays the responses. The token travels in the request to
qlows over HTTPS; treat it like a password.

---

## Troubleshooting

- **`No qlows token found`** — run `qlows-mcp login`, or set `QLOWS_TOKEN`.
- **`Token missing, invalid, or expired`** — the token was revoked or expired;
  mint a new one at https://app.qlows.com/mcp and re-run `login`.
- **`Rate limit exceeded`** — 60 requests/min per token; wait and retry.
- **Client doesn't see `qlows`** — restart the client after editing config;
  validate the JSON (a stray comma silently breaks it); check the client's MCP
  logs.

Verify end-to-end with the
[MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector npx @qlows/mcp
```

---

## Privacy & security

- Read-only: no tool writes back to your qlows account.
- The connector stores only your token, locally, at `~/.qlows/config.json`
  (permissions `0600`). It collects no telemetry.
- Tokens are SHA-256-hashed at rest on the qlows server and can be revoked
  instantly at https://app.qlows.com/mcp.
- Privacy policy: https://qlows.com/privacy

---

## Roadmap

- **One-click browser auto-capture** for `login` (loopback callback).
- **Anthropic Connector Directory** listing — requires OAuth 2.1 + PKCE and
  metadata discovery on the qlows server; tracked as a backend follow-up. This
  connector + the MCP Registry listing are the interim distribution path.
- **Desktop Extension (`.mcpb`)** bundle for one-click Claude Desktop install.

---

## Development

```bash
npm install
npm run build
QLOWS_TOKEN=… QLOWS_BASE_URL=http://localhost:3000 node dist/index.js test
```

Publishing is automated on `v*` tags (see `.github/workflows/release.yml`):
npm publish → MCP Registry publish via GitHub OIDC.

## License

MIT