Metadata-Version: 2.4
Name: softkad-mcp
Version: 0.1.3
Summary: MCP server that consumes the APIDIAN 2026 API (Softkad DIAN UBL 2.1 e-invoicing)
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.5
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

# softkad-mcp

MCP server for **APIDIAN 2026** — Softkad's DIAN UBL 2.1 e-invoicing service (Colombia).

Connect your AI assistant (Claude, ChatGPT, Cursor, etc.) to the APIDIAN API to:
- Emit electronic invoices, credit notes, debit notes
- Manage companies, certificates, and resolutions
- Query documents, customers, and DIAN tables
- Download XML/PDF files and check DIAN status

---

## Prerequisites

- [uv](https://docs.astral.sh/uv/) installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
- An **APIDIAN company token** (obtained by registering a company in the platform)

---

## Quick start — Claude Desktop

Paste this into `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "softkad-apidian": {
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--token", "TU_TOKEN_AQUI",
        "--no-verify-ssl"
      ]
    }
  }
}
```

Replace `TU_TOKEN_AQUI` with your APIDIAN company token. Restart Claude Desktop completely (Cmd+Q → reopen).

### Alternative: token via environment variable (more secure)

```json
{
  "mcpServers": {
    "softkad-apidian": {
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--no-verify-ssl"
      ],
      "env": {
        "APIDIAN_MCP_TOKEN": "TU_TOKEN_AQUI"
      }
    }
  }
}
```

---

## Quick start — ChatGPT Desktop

Paste into `~/Library/Application Support/OpenAI/ChatGPT/mcp.json`:

```json
{
  "mcpServers": {
    "softkad-apidian": {
      "command": "uvx",
      "args": [
        "--from", "softkad-mcp",
        "softkad-mcp-bridge",
        "https://apidian-mcp.softkad.co/sse",
        "--token", "TU_TOKEN_AQUI",
        "--no-verify-ssl"
      ]
    }
  }
}
```

---

## Quick start — Cursor (SSE direct)

```json
{
  "mcpServers": {
    "softkad-apidian": {
      "type": "sse",
      "url": "https://apidian-mcp.softkad.co/sse?token=TU_TOKEN_AQUI"
    }
  }
}
```

---

## Available tools

### Configuration
- `apidian_company` — Register / update a company (returns token on creation)
- `apidian_company_get` — Query a company by NIT
- `apidian_certificate_upload` — Upload digital certificate `.p12`
- `apidian_register_software` — Register billing software
- `apidian_create_resolution` — Create a resolution

### Catalog & Query
- `apidian_documents_list` — List documents by date/search
- `apidian_customers_list` / `apidian_customer_get` / `apidian_customer_search`
- `apidian_items_list` / `apidian_item_get`
- `apidian_payment_forms` / `apidian_payment_methods` — DIAN tables
- `apidian_information` — Query DIAN taxpayer info (RUT)
- `apidian_download` — Download XML / PDF

### Emission
- `apidian_invoice` — Sales invoice
- `apidian_credit_note` / `apidian_debit_note`
- `apidian_support_document` / `apidian_eqdoc`
- `apidian_payroll` — Payroll document
- `apidian_invoice_mandate` — Invoice with mandate (factoring)

### Status
- `apidian_status_zip` — Query by ZIP_KEY
- `apidian_status_document` — Query by CUFE/CUNE
- `apidian_events_document` — List registered events

### Auxiliary
- `apidian_next_consecutive` — Next consecutive number
- `apidian_whatsapp_send` — Send WhatsApp messages

---

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| `softkad-mcp-bridge was not found` | Missing `--from softkad-mcp` | Add it to args |
| `falta el token` | No `--token` or `APIDIAN_MCP_TOKEN` | Add `--token` or set env |
| `SSL: CERTIFICATE_VERIFY_FAILED` | Let's Encrypt cert not trusted | Add `--no-verify-ssl` |
| Server not showing in Claude | Claude not restarted | Close fully (Cmd+Q) and reopen |
| "Token no válido" | Token expired | Regenerate via company registration |

---

## Developer documentation

For local development, testing, and server deployment:
📖 [Full README on GitHub](https://github.com/finakad/apidiancol-mcp)

---

**Softkad** — [softkad.com](https://softkad.com)
