# conservice-credlookup MCP

A stdio MCP server (TypeScript/Node) that resolves a template's logins and **returns their
plaintext credentials to the calling agent** — most often so the agent can fill a login form via
the Playwright MCP.

## ⚠️ This is NOT a credBroker

This server is the deliberate **inverse** of `conservice-credbroker-mcp` (v1), `conservice-credbroker-mcp-v2`,
and `credBroker-v3`. Those brokers were built to keep the credential value **out** of the agent's
context: they own a browser and fill the login form internally, returning only status / a CDP
endpoint. **This server intentionally returns the raw credential values** to the agent.

It exists in preparation for relaxing the credential-obfuscation requirement. Use the brokers when
you must keep credentials out of the LLM context; use this when the agent is allowed to handle them
directly. Don't confuse the two.

## What it does

1. `get_resolution_sql(template_name)` → returns the canonical SQL that maps a template name to its
   top-N `URLTemplateItemGroupID`s (ordered by `PriorityRank`). **This server does not run SQL.**
2. You run that SQL via the **`conservice-sqlserver`** MCP to get the group IDs.
3. `get_credentials(group_ids, template_name?)` → calls the Provider Credentials Service (PCS) for
   each ID and **returns the plaintext credential rows** (`{fieldName, value}`, authoritative order:
   `credentials[0]` = credential 1, etc.).
4. You fill those values into the login form via the Playwright MCP.

It is **DB-free** (group-id resolution is the caller's job, same stance as credbroker v2 §3.4),
owns no browser, solves no captcha, and holds no session state.

## Tools

| Tool | Input | Output |
|---|---|---|
| `get_credentials` | `group_ids: number[]` (1–5), `template_name?` | `{ template_name?, logins: [{ group_id, credentials: [{fieldName,value}] } \| { group_id, error }] }` |
| `get_resolution_sql` | `template_name`, `project_id?`=3, `top?`=5 | `{ sql }` |
| `health` | — | `{ ok, pcs_url, identity_kind }` |

## Configuration (env)

| Var | Default | Purpose |
|---|---|---|
| `CREDLOOKUP_PCS_URL` | **required** | PCS base URL, e.g. `https://providercredentials.conservice.com/api/v1` |
| `CREDLOOKUP_APP_USER_TARGET` | `ApplicationUser` | Windows Credential Manager target for Basic auth |
| `CREDLOOKUP_APP_USER` / `CREDLOOKUP_APP_PASS` | — | env override for the identity (CI/Linux) |
| `CREDLOOKUP_APP_CRED_FILE` | — | JSON `{username,password}` identity file (alt to env/CredMan) |

On Windows the Basic-auth identity is read from the Generic credential named `ApplicationUser`
(same as the brokers and the Harvest `CredentialProvider`) — no secret in the config.

## Build & run

```bash
npm install
npm run build      # tsc --noEmit + esbuild -> dist/index.js  (the gate)
npm start          # node dist/index.js
```

## Registration (user level)

Add to `~/.claude.json` under `mcpServers`:

```json
"conservice-credlookup": {
  "type": "stdio",
  "command": "node",
  "args": ["C:\\Users\\mbrotherson\\repos\\conservice-credlookup-mcp\\dist\\index.js"],
  "env": { "CREDLOOKUP_PCS_URL": "https://providercredentials.conservice.com/api/v1" }
}
```

MCP processes don't hot-reload — restart the Claude Code session to pick up changes.

## End-to-end workflow

```
get_resolution_sql("MunicipalOnlinePayments.ForneyTX")
  → conservice-sqlserver.execute_query(<sql>)        → [groupId, ...]
  → get_credentials(group_ids=[...])                 → plaintext {fieldName, value} rows
  → Playwright MCP fills the login form
```