# tkawen

**The MCP server for Algeria.** Real Algerian data for any AI assistant — all
**69 wilayas**, **1,581 communes**, phone validation, plus e-commerce,
cash-on-delivery economics, credential verification, certified talent and
professional training. **35 tools. Zero dependencies. No API key.**

```bash
npx -y tkawen
```

---

## Why this exists

Ask any model how many provinces Algeria has and it will tell you **58**.

Algeria has had **69 wilayas since 16 November 2025**, when eleven delegated
provinces were promoted. Ask for the communes of Timimoun and the model invents
plausible Arabic place names. Ask whether `0770112233` is a valid Algerian
number and it guesses.

That is not a gap a larger model closes. It is a data problem, and this is the
data.

```
> How many wilayas does Algeria have, and list them?

Algeria — 69 wilayas, 1,581 communes.
The 2025 reform promoted 11 delegated provinces to full wilayas on 16 Nov 2025.
Any list of 58 is stale.

01  Adrar                  أدرار                   16 communes
02  Chlef                  الشلف                   35 communes
...
69  El Abiodh Sidi Cheikh  الأبيض سيدي الشيخ        9 communes
```

## Install

Add it to your MCP client's config:

```json
{
  "mcpServers": {
    "tkawen": {
      "command": "npx",
      "args": ["-y", "tkawen"]
    }
  }
}
```

Works with **Claude Desktop**, **Claude Code**, **Cursor**, **Windsurf**,
**Cline**, **Zed** and anything else that speaks MCP over stdio. That is the
whole installation — no account, no key, no signup.

---

## 🇩🇿 The Algeria Data API

The flagship. Two tools, answered from a local dataset, so they respond in
milliseconds and keep working even when every other service is down.

### `algeria_geospatial`

| Ask | Get |
|---|---|
| `{}` | all 69 wilayas, Arabic + Latin, with commune counts |
| `{"wilaya": "16"}` | Alger — الجزائر, 57 communes |
| `{"wilaya": "الجزاير"}` | same wilaya — misspellings, `أ/إ/آ`, `ة/ه`, `ى/ي` and tashkeel are all folded |
| `{"wilaya": "Timimoun", "include_communes": true}` | every commune with its postal code |
| `{"query": "Ain"}` | free search across all 1,581 communes, either script |
| `{"postal_code": "23001"}` | commune عنابة, wilaya 23 |

Latin and Arabic are equal citizens: `Alger`, `الجزائر`, `الجزاير` and `alger`
all resolve to wilaya 16.

### `algeria_telecom_validator`

Accepts every format an Algerian actually writes — `+213…`, `00213…`, `213…`,
bare 9-digit, spaces, dashes, and **Arabic-Indic digits** (`٠٥٥٥١٢٣٤٥٦`):

```
input:    ٠٥٥٥١٢٣٤٥٦
local:    0555123456
E.164:    +213555123456
whatsapp: 213555123456
type:     mobile
issuer:   Ooredoo (originally allocated)
```

Mobile (`05` / `06` / `07`) and Algérie Télécom landlines (`02` / `03`) are both
validated.

**Two things it will not do**, because being useful matters more than looking
complete:

- **The operator is the *original* allocation.** Number portability has been in
  force in Algeria since 2017, so `07` no longer proves Djezzy. Reported as
  "originally allocated", never as fact.
- **Landlines are not mapped to a wilaya.** Algerian area codes do not follow
  wilaya numbering — Algiers is `021` in wilaya 16, Oran `041` in wilaya 31.
  There is no authoritative area-code table here, and inventing one would put
  made-up geography inside the tool built to stop models inventing Algerian
  geography.

---

## The other 33 tools

Start with **`tkawen_search_tools`** — describe what you want in plain words and
it returns only the tools that fit, instead of loading 35 schemas into your
context. It understands Arabic, French and English.

**E-commerce (MyStoq)** — `cod_profit` (real net profit including the refusal
rate) · `order_risk` (COD fraud scoring) · `yalidine_delivery` (return rates and
delivery times by wilaya) · `search_stores` · `get_store` · `list_plans` ·
`platform_stats` · `create_store` · `create_product` · `set_price` · `publish` ·
`delete_product`

**Credentials (AlgeriaCertify)** — `verify_certificate` ·
`search_certified_talent` · `match_talent_to_job` · `get_talent_profile` ·
`list_specialties` · `list_institutions` · `platform_stats`

**Training** — `search_trainings` · `get_training` · `list_categories` ·
`request_quote` · `list_individual_trainings` · `catalogue_stats`

**Meetings (LIQAA)** — `create_instant_room` · `list_plans` ·
`platform_capacity` · `platform_stats`

**Meta** — `tkawen_search_tools` · `tkawen_overview` · `tkawen_recommend` ·
`tkawen_verify`

Real questions these answer:

| | |
|---|---|
| «بعت بـ 4500 دج، شريت بـ 2200، 28% إرجاع — شحال يبقى لي؟» | `mystoq__cod_profit` |
| "Quel est le taux de retour vers Adrar ?" | `mystoq__yalidine_delivery` |
| "Verify Algerian certificate ACG-2026-1184" | `certify__verify_certificate` |
| "Find certified HSE professionals in Oran" | `certify__match_talent_to_job` |

## Writing, not just reading

Most tools are read-only and need nothing. The ones that **create** things act
on a real account and need a token:

```json
{
  "mcpServers": {
    "tkawen": {
      "command": "npx",
      "args": ["-y", "tkawen"],
      "env": { "TKAWEN_TOKEN": "your-token" }
    }
  }
}
```

Without one they refuse. Nothing is created by accident.

## Architecture

A **stdio bridge**, ~190 lines, to the TKAWEN Intelligence Gateway at
`https://mcp.tkawen.com`. Worth knowing exactly what that means:

- **Your questions leave your machine.** Tool calls go to `mcp.tkawen.com` over
  HTTPS. If that is not acceptable for your data, don't install it. Said here
  rather than buried in a privacy page.
- **The tools are not in this package.** They live on the gateway, so a tool
  added on a Tuesday works for you with no upgrade and no version skew.
- **Zero dependencies.** Node's built-in `fetch` and nothing else — `npx` stays
  fast, and there is no dependency tree to compromise on a path that talks to a
  live API.
- **stdout carries the protocol and nothing else.** One stray `console.log`
  corrupts a JSON-RPC stream and the client reports "server disconnected" with
  no clue why. Every diagnostic goes to stderr.
- **It fails correctly.** Gateway down, timeout, malformed line, non-JSON reply:
  you get a proper JSON-RPC error and a clean exit, never a crash or a corrupted
  stream. Each of those is a test.

Registered in the official MCP registry as **`com.tkawen/intelligence-gateway`**.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `TKAWEN_TOKEN` | — | Bearer token for the write tools |
| `TKAWEN_MCP_URL` | `https://mcp.tkawen.com/` | Point at a different gateway |
| `TKAWEN_TIMEOUT_MS` | `30000` | Per-request timeout |

**Node 18+.** Older versions have no global `fetch`; the bridge says so and
exits rather than failing in a way you would have to debug.

## Tests

```bash
npm test     # 10 tests, no network — framing, errors, stdout purity
npm run smoke # hits the live gateway, asserts 69 wilayas
```

The unit tests run against a mock gateway on purpose: a red `test` means this
package broke, and a red `smoke` means the gateway is unreachable. Collapsing
the two would make every network blip look like a code regression.

## License

MIT — built in Annaba by [TKAWEN](https://tkawen.com).