# IBM Sales Guidance Tool — MCP Server

An MCP (Model Context Protocol) server that exposes the [IBM Sales Guidance Tool](https://github.com/slaphen1/ibm-sales-guidance-tool) as tools Bob can invoke directly from chat.

Once registered, Bob can:
- Ask the IBM AskSales AI assistant questions about products, deals, and competitors
- Search IBM AskSales content (playbooks, battle cards, competitive intel)
- Generate a full 4-section Client Roadmap for any named account
- Check live Watson Assistant + AskSales connectivity status

---

## Tools

| Tool | Description |
|---|---|
| `sales_guidance_diag` | Check Watson + AskSales connectivity and latency — run this first when debugging |
| `sales_guidance_chat` | Ask the AskSales Watson Assistant a question (product knowledge, objections, strategy) |
| `sales_guidance_asksales` | Search IBM AskSales content library for playbooks or competitive intel |
| `sales_guidance_roadmap` | Generate a full 4-section IBM Client Roadmap (takes 30–90s) |

---

## Setup

### 1. Install dependencies and build

```bash
cd sales-guidance-mcp
npm install
npm run build
```

### 2. Register with Bob

Add the following to your `.bob/mcp.json` (workspace scope):

```json
{
  "mcpServers": {
    "sales-guidance": {
      "command": "node",
      "args": ["/absolute/path/to/sales-guidance-mcp/build/index.js"],
      "env": {
        "SALES_GUIDANCE_URL": "https://ibm-sales-guidance-tool.2ck01rg2j69e.us-east.codeengine.appdomain.cloud",
        "SELLER_EMAIL": "your.email@ibm.com"
      }
    }
  }
}
```

Replace `/absolute/path/to/sales-guidance-mcp` with the real path on your machine.

### 3. Verify

Ask Bob: **"Check the sales guidance tool status"** — it will call `sales_guidance_diag` and report Watson + AskSales connectivity.

---

## Configuration

All config is via environment variables in the `env` block of `mcp.json`:

| Variable | Required | Default | Description |
|---|---|---|---|
| `SALES_GUIDANCE_URL` | ✅ Yes | — | Base URL of the deployed Sales Guidance Tool |
| `SELLER_EMAIL` | No | `ibm-bob@ibm.com` | IBM seller email passed to Watson as `user_id` and `email_address` skill variable |
| `REQUEST_TIMEOUT_MS` | No | `100000` | HTTP timeout in ms. Roadmap calls can take up to 90s — keep this above 90000. |

---

## Architecture

```
Bob (chat) ──── MCP tool call ────► sales-guidance-mcp (stdio)
                                         │
                                         │ HTTPS
                                         ▼
                              IBM Sales Guidance Tool
                              (Code Engine, us-east)
                                         │
                              ┌──────────┴──────────┐
                              │                     │
                    Watson Assistant          IBM AskSales
                    (AskSales skill)          (when configured)
```

The MCP server is a thin HTTP client — it calls the deployed Next.js app's API routes over HTTPS. No local services, no Docker, no credentials stored in this repo.

---

## Known issues

### Watson Assistant / AskSales outage (2026-07-21)
IBM reported degradation on IBM product queries in Watson Assistant / AskSales. Symptoms: `sales_guidance_chat` and `sales_guidance_roadmap` time out. Run `sales_guidance_diag` — if `watson.latencyWarning` is set, the outage is still active. Retry later.

### AskSales search returns empty results
`sales_guidance_asksales` requires real AskSales credentials on the server side (`ASKSALES_API_URL`, `ASKSALES_API_KEY`). Run `sales_guidance_diag` — if `asksales.enabled` is `false`, placeholder credentials are in use and this is expected.

### Roadmap timeout
The `sales_guidance_roadmap` tool has a 100s client timeout (default). Watson takes 30–90s to generate a full 4-section roadmap. If you consistently hit timeouts, set `REQUEST_TIMEOUT_MS=120000` in the env block.

---

## Development

```bash
npm run build    # compile TypeScript → build/index.js
npm run dev      # watch mode
```

The source is a single file: [`src/index.ts`](src/index.ts). Each tool is registered with `server.registerTool()` using the MCP SDK v2 API.