Metadata-Version: 2.4
Name: squadco-mcp
Version: 0.1.0
Summary: SquadCo API documentation as an MCP server
Requires-Python: >=3.10
Requires-Dist: citekit>=0.1.0
Requires-Dist: mcp[cli]>=1.2.0
Description-Content-Type: text/markdown

# SquadCo API Docs MCP Server

> **Disclaimer**: This is a community-driven project and is **not affiliated with or endorsed by SquadCo**. It is built by developers, for developers, using the official public SquadCo documentation.

The SquadCo MCP Server provides your AI coding assistant (Claude, Cursor, Windsurf, etc.) with direct, structured access to the full SquadCo API documentation. 

Stop switching between your editor and the browser. Get precise API specs, validation logic, and code samples for SquadCo integrations directly in your chat.

---

## Key Features

- **Direct Knowledge**: Instant access to documentation for Payments, Transfers, Virtual Accounts, VAS, and Webhooks.
- **Accurate Specs**: Returns the exact technical markdown sections—no fuzzy hallucinations.
- **Developer Ready**: Full details on Sandbox environments, test cards, and security validation.
- **No Clone Needed**: Run directly using `uvx` or `pipx`.

---

## Capabilities

The MCP server covers the entire SquadCo ecosystem:

### 1. Payments and Collections
*   **Checkout Options**: Integration guides for the Squad Payment Modal (Inline), Redirect flows, and mobile-ready implementations.
*   **Direct API**: Technical specs for server-to-server payment initiation and transaction verification.
*   **Alternative Methods**: Documentation for POS Payment, Direct Debit, and E-commerce plugins (WooCommerce).
*   **Testing**: A comprehensive list of test card numbers, expiry dates, and CVVs for sandbox testing.

### 2. Transfers and Payouts
*   **Fund Transfers**: How to move funds from your Squad Wallet to any bank account in Nigeria.
*   **Account Lookup**: recipient name verification logic to ensure transaction accuracy.
*   **Wallet Management**: Checking ledger balances and transaction history.
*   **Bank Codes**: A complete, searchable list of all supported bank and microfinance codes.

### 3. Virtual Accounts
*   **Account Generation**: Creating dedicated virtual accounts for customers to receive automated bank transfers.
*   **Dynamic V2**: Advanced specifications for high-frequency, dynamic account creation and management.
*   **Metadata**: Attaching custom data to accounts for easier reconciliation.

### 4. Value Added Services (VAS)
*   **Airtime and Data**: API specs for selling mobile airtime and data bundles.
*   **Bills Payment**: Integration for electricity bills and other utility services.
*   **SMS Services**: Managing SMS buckets and automated messaging.

### 5. Operations and Security
*   **Webhooks**: Step-by-step setup for POST notifications, IP filtering, and signature verification.
*   **Security**: Technical guides for HMAC-SHA512 validation and AES-256 encryption/decryption.
*   **Management**: Detailed flows for Refunds, Disputes, and Chargebacks.

### 6. Sandbox and Testing
*   **Environment Setup**: Detailed information on using the `sandbox-api.squadco.com` endpoints.
*   **Test Assets**: A full database of test card numbers, CVVs, and standard OTP codes for simulating successful and failed payments.
*   **Transfer Simulation**: Specific API flows for simulating incoming bank transfers to virtual accounts in a test environment.

---

## Tools

| Tool | Purpose |
|---|---|
| `search_docs` | The main entry point. Search for any SquadCo feature (e.g., "AES encryption"). |
| `list_docs` | Browse all available API documentation files. |
| `get_doc_structure` | View the structural map of a specific document to find precise sections. |
| `resolve_section` | Fetch the full technical content, URLs, and code samples for a section. |

---

## Client Configuration Guide

Depending on your preferred AI assistant, the configuration process varies slightly. Below are the specific setup steps for the most common MCP-compatible clients.

### 1. Claude Desktop
Claude Desktop looks for a central configuration file to load MCP servers.

**Config File Locations:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

**Setup:** Open the file and add the `squadco-docs` entry to the `mcpServers` object.
**Note:** In Claude Desktop, go to Settings > Developer > Edit Config to open this file directly.

### 2. Cursor
Cursor provides a native UI for managing MCP servers, making it one of the easiest to configure.

1. Open Cursor Settings (Gear icon in the top right).
2. Navigate to Features (or Tools & Integrations).
3. Scroll down to MCP Servers and click + Add New MCP Server.
4. Set the type to `command` and paste the following:
   - **Name**: `squadco-docs`
   - **Command**: `uvx squadco-mcp` (or the absolute path to uvx).

### 3. Windsurf (by Codeium)
Windsurf uses a `settings.json` file to manage its Cascade AI capabilities.

**Config File Locations:**
- **macOS**: `~/Library/Application Support/Windsurf/User/settings.json`
- **Windows**: `%APPDATA%\Windsurf\User\settings.json`

**Configuration:** Add the server under the `mcpServers` key. Windsurf also supports a simplified `serverUrl` if you are hosting the MCP server remotely.

### 4. Visual Studio Code
For standard VS Code users, MCP support is typically handled via the MCP Client extension or workspace-specific configurations.

- **Workspace Config**: Create a `.vscode/mcp.json` file in your project root. This allows you to share the MCP server configuration with teammates who also use the repository.
- **Global Config**: Some extensions allow a global `mcp.json` in your user profile for tools you want available across all projects.

### 5. Claude Code (CLI)
For users of the Claude CLI, you can add the server using the built-in add command:
`claude mcp add squadco-mcp -- uvx squadco-mcp`

---

## MCP Configuration Reference

| Client | MCP Integration Method | squadco-mcp Configuration |
|---|---|---|
| Claude Desktop | JSON-RPC over stdio | Add to `mcpServers` in `claude_desktop_config.json` |
| Cursor | Native MCP UI | Use `uvx squadco-mcp` as the command |
| Windsurf | Cascade MCP | Add to `mcpServers` in `settings.json` |
| VS Code | Workspace MCP | Add to `.vscode/mcp.json` |
| Claude Code | CLI MCP Manager | Run `claude mcp add squadco-mcp -- uvx squadco-mcp` |

---

## Troubleshooting Tips

- **Absolute Paths**: Some clients (especially Claude Desktop) have limited environment path access. If `uvx` or `pipx` isn't found, use the absolute path to the executable (e.g., `/usr/local/bin/uvx`).
- **Restart Required**: Most desktop clients require a full restart (not just closing the window) to pick up changes made directly to JSON configuration files.
- **Logs**: If the server fails to connect, check the developer console (usually Ctrl+Shift+I or Cmd+Option+I) for JSON-RPC connection errors.

---

## Technical Details

The SquadCo MCP Server uses [CiteKit](https://abdushakurob.github.io/citekit) to provide high-fidelity documentation access to AI agents.

Unlike standard RAG (Retrieval-Augmented Generation) which uses vector-based similarity, this server employs a structural mapping approach:

- **Pre-computed Mapping**: Documentation is analyzed during ingestion to create a structural index of all API endpoints, parameters, and code blocks.
- **Deterministic Resolution**: The AI assistant identifies the specific node it needs from the map and resolves the content locally from the bundled markdown files.
- **Precision Context**: By resolving exact sections rather than chunked text, the server ensures the AI receives clean, relevant context without noise.

**Stack:**
- **Core Engine**: [CiteKit](https://abdushakurob.github.io/citekit) (by [@abdushakurob](https://github.com/abdushakurob))
- **Scraper**: [crawl4ai](https://github.com/unclecode/crawl4ai)
- **Protocol**: [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)

---