Metadata-Version: 2.4
Name: pinelabs-mcp-server
Version: 0.1.4
Summary: A Model Context Protocol (MCP) server for Pine Labs payment APIs
Author: Pine Labs
License: MIT
Project-URL: Homepage, https://github.com/pinelabs/pinelabs-mcp-server
Project-URL: Repository, https://github.com/pinelabs/pinelabs-mcp-server
Project-URL: Issues, https://github.com/pinelabs/pinelabs-mcp-server/issues
Keywords: mcp,pinelabs,payments,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=3.2.0
Requires-Dist: fastapi==0.135.1
Requires-Dist: httpx==0.28.1
Requires-Dist: pydantic>=2.12.0
Requires-Dist: uvicorn==0.41.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: prometheus-client>=0.24.0
Requires-Dist: opentelemetry-api>=1.40.0
Requires-Dist: opentelemetry-sdk>=1.40.0
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.40.0
Requires-Dist: redis>=5.0
Requires-Dist: dateparser>=1.2.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: respx; extra == "dev"

# Pine Labs MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for **Pine Labs payment APIs**. Connect your AI assistant — Claude Desktop, Cursor, VS Code, Windsurf, or any MCP-compatible client — to Pine Labs and manage payments, refunds, orders, payouts, settlements, and more through natural language.

> **[Full Documentation](https://developer.pinelabsonline.com/docs/mcp-server-overview)** · **[Available Tools](https://developer.pinelabsonline.com/docs/mcp-server-tools)** · **[Use Cases](https://developer.pinelabsonline.com/docs/mcp-server-use-cases)** · **[FAQs](https://developer.pinelabsonline.com/docs/mcp-server-faqs)**

---

## Prerequisites

- **Python 3.10+** — [Download](https://www.python.org/downloads/)
- **Pine Labs Client Credentials** — Get your `Client ID` and `Client Secret` from the [Pine Labs developer portal](https://developer.pinelabsonline.com/)

---

## Installation

```bash
pip install pinelabs-mcp-server
```

To verify the installation:

```bash
pinelabs-mcp-server --help
```

---

## Quick Start

### 1. Set your credentials

Create a `.env` file in your working directory or export the variables directly:

```bash
export PINELABS_CLIENT_ID="your_client_id"
export PINELABS_CLIENT_SECRET="your_client_secret"
export PINELABS_ENV="uat"   # use "prod" for production
```

### 2. Start the server

```bash
pinelabs-mcp-server
```

The server starts on `http://0.0.0.0:8000/mcp` using Streamable HTTP transport by default.

### 3. Connect your AI client

Point your MCP-compatible AI client to the running server endpoint — see [AI Client Configuration](#ai-client-configuration) below.

---

## AI Client Configuration

Add the following to your AI client's MCP configuration file:

### Claude Desktop

File: `claude_desktop_config.json`

```json
{
  "mcpServers": {
    "pinelabs": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-Client-Id": "your_client_id",
        "X-Client-Secret": "your_client_secret"
      }
    }
  }
}
```

### Cursor

File: `~/.cursor/mcp.json`

```json
{
  "mcpServers": {
    "pinelabs": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-Client-Id": "your_client_id",
        "X-Client-Secret": "your_client_secret"
      }
    }
  }
}
```

### VS Code

File: `.vscode/mcp.json` (in your project root)

```json
{
  "servers": {
    "pinelabs": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-Client-Id": "your_client_id",
        "X-Client-Secret": "your_client_secret"
      }
    }
  }
}
```

> **Note:** VS Code uses `"servers"` instead of `"mcpServers"` as the top-level key.

---

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PINELABS_CLIENT_ID` | Yes | — | Your Pine Labs client ID |
| `PINELABS_CLIENT_SECRET` | Yes | — | Your Pine Labs client secret |
| `PINELABS_ENV` | No | `uat` | Environment: `uat` or `prod` |
URL |
| `PINELABS_TOKEN_URL` | No | Auto from env | Override the token endpoint URL |
| `HOST` | No | `0.0.0.0` | Server bind address |
| `PORT` | No | `8000` | Server port |
| `LOG_LEVEL` | No | `INFO` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
| `LOG_FORMAT` | No | `text` | Log format: `text` or `json` |
| `TOOLS` | No | — | Comma-separated tool filter (see below) |
| `REDIS_HOST` | No | `localhost` | Redis host for token caching |
| `REDIS_PORT` | No | `6379` | Redis port |
| `REDIS_DB` | No | `0` | Redis database index |

---

## Available Tools

The server exposes **56 tools** across these categories:

| Category | Examples |
|----------|----------|
| **Payment Links** | Create, retrieve, cancel, and resend payment links |
| **Orders** | Create, track, and manage checkout orders |
| **Refunds** | Create and retrieve refund details |
| **Payouts** | Initiate and track payouts |
| **Settlements** | Query settlement details and cancel settlements |
| **Subscriptions** | Create and manage recurring subscriptions |
| **Card Payments** | Server-to-server card payment flows with OTP |
| **UPI / QR** | Generate QR codes for UPI intent payments |
| **API Docs** | Search Pine Labs API documentation |
| **Code Generation** | Generate integration code snippets |

See the [complete tools reference](https://developer.pinelabsonline.com/docs/mcp-server-tools) for details.

---

## Tool Filtering

You can control which tools the server exposes using the `TOOLS` environment variable. Tools are classified by **operation** (`read` / `write` / `destructive`) and **category** (e.g., `payment_links`, `orders`, `refunds`). Use a comma-separated mix of operation types and domain categories:

```bash
# Only read tools
TOOLS=read pinelabs-mcp-server

# Only payment link tools
TOOLS=payment_links pinelabs-mcp-server

# Read + write tools (excludes destructive)
TOOLS="read,write" pinelabs-mcp-server

# Read tools for orders and payment_links only
TOOLS="read,orders,payment_links" pinelabs-mcp-server
```

**Short aliases** are supported:

| Alias | Expands To |
|-------|------------|
| `payment` | `payment_links` |
| `order` | `orders` |
| `refund` | `refunds` |
| `payout` | `payouts` |
| `settlement` | `settlements` |
| `subscription` | `subscriptions` |

---

## Running with Docker

```bash
docker build -t pinelabs-mcp-server .

docker run -p 8000:8000 \
  -e PINELABS_CLIENT_ID="your_client_id" \
  -e PINELABS_CLIENT_SECRET="your_client_secret" \
  -e PINELABS_ENV="uat" \
  pinelabs-mcp-server
```

---

## Development

```bash
# Clone the repository
git clone https://github.com/Plural-Pvt/pinelabs-mcp-server.git
cd pinelabs-mcp-server

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-test.txt  # for running tests

# Run the server locally
python main.py

# Run tests
pytest
```

---

## Troubleshooting

| Issue | Fix |
|-------|-----|
| `pinelabs-mcp-server` command not found | Ensure `pip install pinelabs-mcp-server` completed successfully and the install directory is in your `PATH` |
| Authentication errors | Verify your `PINELABS_CLIENT_ID` and `PINELABS_CLIENT_SECRET` are correct |
| Tools not appearing in AI client | Restart your AI assistant after configuring the MCP endpoint; check server logs for errors |
| Connection refused | Ensure the server is running (`pinelabs-mcp-server`) and the port matches your client config |
| Redis connection errors | Redis is optional for local dev — the server falls back to in-memory token caching |

---

## Also Available on npm

If you prefer a Node.js-based setup with automatic AI client configuration, use the **npm package** instead:

```bash
npx pinelabs-mcp configure --client-id=YOUR_ID --client-secret=YOUR_SECRET
npx pinelabs-mcp setup cursor   # or: claude-desktop, vscode, windsurf
```

See [pinelabs-mcp on npm](https://www.npmjs.com/package/pinelabs-mcp) for details.

---

## License

MIT — see [LICENSE](./LICENSE) for details.
