API + MCP

1. Tezkor start

1. Kirish (Google yoki gate).
2. Keys → yangi kalit → mantiq_sk_… ni bir marta nusxa oling.
3. Cursor MCP ga ulang (§3) yoki curl bilan sinang.
4. Birinchi chaqiruv: whoami — workspace_id shu yerdan.

export MANTIQ_API_URL=https://mantiq.xubi.org
export MANTIQ_API_KEY='mantiq_sk_…'

curl -sS "$MANTIQ_API_URL/api/mcp" \
  -H "Authorization: Bearer $MANTIQ_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'

2. Auth

• Web: session cookie · MCP/agent: Authorization: Bearer mantiq_sk_…
• Tenant faqat credential’dan — body’dagi id a’zolik bilan tekshiriladi.
• Boshqa tenant → 404 (leakli 403 emas).
• CRUD: GET/POST /api/settings/api-keys, DELETE …/{id}

3. Cursor / MCP

Endpoint: POST /api/mcp · katalog: GET /api/mcp/tools

{
  "mcpServers": {
    "mantiq": {
      "type": "http",
      "url": "https://mantiq.xubi.org/api/mcp",
      "headers": { "Authorization": "Bearer ${MANTIQ_API_KEY}" }
    }
  }
}

Metodlar: initialize, tools/list, tools/call (name + arguments).

4. MCP tools

Identitet

• whoami — account + workspace’lar. Har sessionda birinchi.

Map

• map_list · map_read (yozishdan oldin) · map_add (batch, max 120, parent→child)
• map_update_node · map_delete_node · map_link / map_unlink
• map_image_add (base64 yoki SVG) · map_image_read

kind: idea · action · decision · comment. Parent/from/to — id yoki title.

{
  "name": "map_add",
  "arguments": {
    "workspace_id": "ws_…",
    "nodes": [
      { "title": "Backend", "kind": "idea" },
      { "title": "Auth", "kind": "action", "parent": "Backend" }
    ]
  }
}

Process

Status: todo (Reja) → in_progress (Ishda, WIP max 3) → review → done.

• process_summary · process_list · process_get
• process_create · process_from_node · process_update · process_transition

5. REST (qisqa)

• GET /api/health, /api/me, /api/workspaces
• Process: /api/workspaces/{id}/process (+ summary, from-node, PATCH, DELETE)
• Map: /api/boards/{id} (ETag), nodes/edges CRUD, presence

6. Agent oqimi

whoami → map_read / process_summary
     → map_add | process_from_node | process_transition
     → map_read / process_list (tasdiq)

• Yozishdan oldin o‘qing — dublikat yaratmang.
• Katta dump = bitta daraxtli map_add, flat emas.
• Tayyor ish → process_from_node.
• Xato: 401 kalit · 404 ACL · wip_limit:3 Ishda to‘la.

Repo: docs/API_MCP_GUIDE.md · skills: map-architect, process-board