# AGENTS.md — KIRA Agency

> **Built for the agent era.**
> This file follows the 2026 Agent Readability Spec for AI coding agents (Claude Code, Cursor, GitHub Copilot, Devin, etc.).
> It describes KIRA's public API surface, MCP server, and how to integrate with this platform programmatically.

## What This Site Is

**kiraco.org** is the marketing website for KIRA Agency — Kuwait's leading AI automation and marketing company.
- Primary product: **Lojain AI** — WhatsApp AI platform for GCC businesses (24/7 Arabic/English AI agent, payments, CRM)
- Secondary products: Media Buying, Business Consulting, Influencer Campaigns, Digital Loyalty Program, Web Studio
- Public API: contact form submission only (no auth required)
- Platform API: full tenant management via MCP server (auth required)

## Public API

**Base URL**: `https://api.kiragpt.com`
**Spec**: `https://kiraco.org/openapi.yaml`
**Auth**: None required for public endpoints

### Submit a contact inquiry
```
POST https://api.kiragpt.com/kiraco/contact
Content-Type: application/json

{
  "name": "string (required)",
  "company": "string (optional)",
  "email": "email (optional if phone provided)",
  "phone": "+965XXXXXXXX (optional if email provided)",
  "goal": "Lojain AI (WhatsApp automation) | Media Buying | Business Consulting | Influencer Campaigns | Digital Loyalty Program | General inquiry",
  "message": "string (optional)"
}
```

Response 200:
```json
{ "success": true, "message": "Your inquiry has been received. Our team will contact you within 1 business day." }
```

## KIRA MCP Server (Platform API)

For agents that need full platform control — not just contact submission.

**MCP URL**: `https://mcp.kiragpt.com/mcp`
**Transport**: Streamable HTTP (MCP spec 2025-11-05)
**Auth**: Bearer token — `Authorization: Bearer kira_live_<your_key>`
**Get your key**: KIRA Dashboard → Settings → API Keys
**Discovery**: `https://kiraco.org/.well-known/mcp.json`

### What the MCP Server Exposes (67 tools across 4 products)

**Lojain AI — WhatsApp Platform (37 tools)**
- `list_contacts`, `search_contacts`, `get_contact`, `create_contact`, `update_contact`
- `list_conversations`, `get_conversation`, `send_message`, `send_template`
- `list_campaigns`, `create_campaign`, `run_campaign`, `get_campaign_analytics`
- `list_templates`, `get_template_status`
- `get_knowledge_base`, `add_knowledge_document`, `delete_knowledge_document`
- `get_inbox_summary`, `get_analytics_dashboard`
- `list_payment_orders`, `create_payment_link`
- `get_tenant_settings`, `update_bot_settings`

**KiraChats — Instagram Automation (18 tools)**
- `list_engagement_rules`, `create_engagement_rule`, `update_engagement_rule`
- `get_instagram_analytics`, `get_post_insights`
- `list_giveaways`, `create_giveaway`, `get_giveaway_entries`
- `list_dm_conversations`, `send_instagram_dm`

**Social Manager (6 tools)**
- `list_scheduled_posts`, `create_post`, `update_post`, `delete_post`
- `get_social_analytics`, `publish_post_now`

**Web Studio (6 tools)**
- `list_products`, `create_product`, `update_product`
- `list_orders`, `get_order`, `update_order_status`

### Connecting to KIRA MCP in Claude Code

Add to your Claude Code MCP config (`~/.claude/claude_desktop_config.json` or `claude.json`):

```json
{
  "mcpServers": {
    "kira": {
      "command": "python",
      "args": ["/path/to/kira_mcp/run.py"],
      "env": {
        "KIRA_API_KEY": "kira_live_your_key_here",
        "KIRA_TENANT_ID": "your-tenant-uuid",
        "KIRA_API_BASE": "https://api.kiragpt.com"
      }
    }
  }
}
```

Or as a remote MCP server in Claude Pro/Max at `https://mcp.kiragpt.com/mcp` with `Bearer kira_live_<key>`.

## AI Discoverability Files

| File | URL | Format | Purpose |
|---|---|---|---|
| LLM summary | `https://kiraco.org/llms.txt` | text/plain | Company overview for LLMs |
| LLM full context | `https://kiraco.org/llms-full.txt` | text/plain | Complete context, pricing, case studies |
| OpenAPI spec | `https://kiraco.org/openapi.yaml` | application/yaml | Public API spec |
| MCP discovery | `https://kiraco.org/.well-known/mcp.json` | application/json | MCP server card |
| Plugin manifest | `https://kiraco.org/.well-known/ai-plugin.json` | application/json | ChatGPT plugin manifest |
| XML sitemap | `https://kiraco.org/sitemap.xml` | application/xml | Full URL list |

## Response Headers

Every response from kiraco.org includes:
```
Link: </llms.txt>; rel="describedby"; type="text/plain"
X-LLM-Context: https://kiraco.org/llms.txt
X-AI-Plugin: https://kiraco.org/.well-known/ai-plugin.json
X-MCP-Server: https://mcp.kiragpt.com/mcp
```

## Site Architecture for Agents

**nginx serves static HTML for all known routes** — AI crawlers, curl, and direct URL fetches all receive fully rendered HTML with semantic content, structured data, and FAQ schema. There is no JavaScript execution required to read page content.

**React SPA handles in-app navigation** — The SPA shell (`/index.html`) is only served as a fallback for routes not listed in the nginx config. All service pages, resource pages, and key marketing pages have pre-rendered static HTML files.

**Static HTML locations** (under `/opt/kiraco/public/`):
- `/services/lojain/index.html`
- `/services/lojain-lite/index.html`
- `/services/lojain-ai/index.html`
- `/services/media-buying/index.html`
- `/services/business-consulting/index.html`
- `/services/influencer-campaigns/index.html`
- `/services/loyalty-program/index.html`
- `/services/ai-agents/index.html`
- `/services/web-studio/index.html`
- `/services/kira-suite/index.html`
- `/for/restaurants/index.html`, `/for/salons/index.html`, `/for/clinics/index.html`, `/for/real-estate/index.html`, `/for/ecommerce/index.html`
- `/compare/wati-vs-lojain/index.html`, `/compare/respond-io-vs-lojain/index.html`
- `/whatsapp-business-api/index.html`
- `/pricing/index.html`
- `/resources/` (individual articles as `.html` files)

## Key Pages for AI Agents

| Intent | URL |
|---|---|
| What is KIRA? | https://kiraco.org/about |
| Full product list | https://kiraco.org/services |
| WhatsApp AI platform | https://kiraco.org/services/lojain |
| Pricing comparison | https://kiraco.org/services/kira-suite |
| Pricing page | https://kiraco.org/pricing |
| Connect KIRA to Claude | https://kiraco.org/resources/lojain-claude-mcp-integration |
| Submit a lead / inquiry | https://kiraco.org/contact |
| Case studies | https://kiraco.org/case-studies |

## Contact

- **Email**: sales@kiragpt.com
- **WhatsApp**: +965 9786 6044
- **API support**: sales@kiragpt.com (include your tenant ID)