# Kapital Bank E-Commerce API Documentation MCP Server

Model Context Protocol (MCP) Server for the official **Kapital Bank E-commerce API Documentation** built on **Hono.js** and **Cloudflare Workers**.

Custom Domain: `kb.mcp.davidjs.dev`

---

## 🎯 Overview

This MCP Server provides AI models (Claude, Cursor, Copilot, Antigravity, etc.) with authoritative knowledge and code generation capabilities for Kapital Bank's payment gateway without requiring any merchant credentials or live bank execution.

### Key Capabilities
- **Complete Endpoint Specifications**: Exact URLs, HTTP methods, headers, required/optional parameters, and request/response JSON payloads for `POST /order`, `POST /set-src-token`, `POST /set-dst-token`, `POST /exec-tran`, `POST /exec-tran` (Refund & Reversal), and `GET /order/{ID}`.
- **Step-by-Step Payment Flows**:
  - Standard 1-step Purchase (`Order_SMS`)
  - 2-step Preauthorization Hold & Capture (`Order_DMS` Auth + Clearing)
  - Recurring Tokenized Payments (`Order_REC`, `DMSN3D`, `srcToken`)
  - Account-to-Card Transfer (`OCT`, `dstToken`)
  - BirBank Taksit Installments (`TAKSIT=3`, `TAKSIT=6`, `TAKSIT=12`)
- **Code Generation**: Ready-to-copy integration code in **TypeScript**, **Node.js**, **Python**, **PHP**, and **cURL**.
- **Error Dictionary & Diagnostics**: Full lookup for PMO response codes (0–98), decline causes, and order statuses.
- **Official Sandbox Credentials**: Test base URLs, default test login, and test credit card numbers with CVVs and exp dates.

---

## 🛠 Available MCP Tools

| Tool | Description |
|---|---|
| `kb_get_overview` | Base URLs (test & prod), BasicAuth header rules, test credentials |
| `kb_get_endpoint_doc` | Complete parameter spec and payload examples for any endpoint |
| `kb_get_payment_flow` | Step-by-step architecture for SMS, DMS, Recurring, OCT, and Taksit flows |
| `kb_search_docs` | Search knowledge base for any keyword, error code, or parameter |
| `kb_generate_code_sample` | Generate ready-to-run code in TypeScript, Python, PHP, or cURL |
| `kb_explain_response_code` | Lookup PMO response code (0–98) and error explanations |
| `kb_get_test_credentials` | Get sandbox URLs and test card numbers (PAN, CVV, Exp) |

---

## 🔌 Connecting to AI Clients

### 1. OpenAI Codex / Codex CLI
```bash
codex mcp add kapitalbank-docs --url https://kb.mcp.davidjs.dev/sse
```
Or add to `~/.codex/config.json`:
```json
{
  "mcpServers": {
    "kapitalbank-docs": {
      "url": "https://kb.mcp.davidjs.dev/sse"
    }
  }
}
```

### 2. Cursor IDE (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "kapitalbank-docs": {
      "url": "https://kb.mcp.davidjs.dev/sse"
    }
  }
}
```

### 3. Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "kapitalbank-docs": {
      "url": "https://kb.mcp.davidjs.dev/sse"
    }
  }
}
```

---

## 🚀 Local Development & Deploy

```bash
# Test with Bun
bun test

# Run locally
bun run dev

# Deploy to Cloudflare Workers
bun run deploy
```

---

## 📄 License
MIT