# mcp-arabic-toolkit

A small [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server
exposing practical Arabic text utilities. Built with the official `mcp` Python
SDK (FastMCP).

**Demonstrates: MCP server authoring / tool development**

All tools are implemented for real -- deterministic string processing plus one
clearly-labelled heuristic. The pure logic lives in
[`arabic_tools.py`](arabic_tools.py) (no `mcp` dependency), so it is
independently unit-tested; [`server.py`](server.py) is a thin MCP wrapper.

## Tools

| Tool | Description | Example input | Example output |
| --- | --- | --- | --- |
| `normalise_arabic` | NFC-normalises, removes diacritics (harakat/tashkil) and tatweel, and optionally unifies letter variants (alef/yeh/teh-marbuta). | `الْعَرَبِيَّةُ` | `العربية` |
| `strip_tashkeel` | Removes only the diacritics (and, by default, the tatweel); leaves letters as-is. | `كــــتاب` | `كتاب` |
| `transliterate` | Documented, deterministic Arabic→Latin romanisation (simplified DIN 31635 / ALA-LC, ASCII digraphs). | `كَتَبَ` | `{"transliteration": "kataba", "scheme": "din31635-simplified-ascii"}` |
| `detect_dialect` | **Heuristic** dialect guess (Egyptian/Levantine/Gulf/Maghrebi/MSA) from marker words. Not a trained classifier — see limits below. | `شو بدك هلق؟` | `{"dialect": "levantine", "confidence": 1.0, ...}` |
| `count_tokens` | Whitespace-token count plus character and Arabic-character statistics. | `مرحبا يا عالم` | `{"tokens": 3, "characters": 13, ...}` |

### About `detect_dialect` (read this)

`detect_dialect` is an **honest heuristic, not a machine-learning model.** It
counts hand-picked marker words/particles per dialect and returns the highest
scorer. Known limits:

- Only five coarse groups (Egyptian, Levantine, Gulf, Maghrebi, MSA).
- Unreliable on short input, mixed-dialect text, and code-switching.
- `confidence` is a crude ratio (winning hits / total hits), **not** a
  calibrated probability.
- Falls back to MSA with `confidence: 0.0` when no markers are found.

For production-grade detection, train a supervised classifier (e.g. fastText or
a fine-tuned transformer) on a labelled corpus such as MADAR or NADI.

### About `transliterate`

The romanisation is deterministic and documented but intentionally simple:

- No vowel inference — short vowels are produced only from explicit harakat.
- No context-sensitive rules — the article `ال` is always `al-` (no sun-letter
  assimilation), and hamzat al-wasl is not elided.
- Shadda doubles the preceding consonant; sukun emits no vowel.
- One-way (Arabic → Latin); not round-trippable.

## Install

Requires Python 3.10+.

```bash
# Clone, then install the package (editable for local development):
pip install -e .
```

This pulls in the `mcp` SDK and registers a `mcp-arabic-toolkit` console script.

The tests themselves need only `pytest` (no `mcp` SDK):

```bash
pip install pytest
```

## Run

```bash
# Option A: run the module directly (stdio transport)
python server.py

# Option B: run the installed console script
mcp-arabic-toolkit
```

### Register with an MCP client

To use it from Claude Desktop (or any MCP client), add an entry to the client's
MCP server config:

```json
{
  "mcpServers": {
    "arabic-toolkit": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-arabic-toolkit/server.py"]
    }
  }
}
```

## Test

```bash
python -m pytest tests/ -v
```

The suite (`tests/test_tools.py`) imports the pure logic directly and covers
every tool with concrete examples (diacritic/tatweel removal, letter
unification, transliteration with and without harakat, each dialect, and token
counting).

### Quick local check

```bash
python -c "import arabic_tools; print(arabic_tools.normalise_arabic('الْعَرَبِيَّةُ'))"
# -> العربية
```

## Publishing to the MCP registry

This package ships a [`server.json`](server.json) manifest compatible with the
official [MCP registry](https://github.com/modelcontextprotocol/registry).

### Exact metadata (`server.json`)

```json
{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
  "name": "io.github.benjiscollector/mcp-arabic-toolkit",
  "description": "MCP server exposing Arabic text utilities: normalisation, tashkeel stripping, transliteration, a heuristic dialect detector, and token counting.",
  "status": "active",
  "repository": {
    "url": "https://github.com/BenjisCollector/mcp-arabic-toolkit",
    "source": "github"
  },
  "version": "0.2.0",
  "packages": [
    {
      "registryType": "pypi",
      "registryBaseUrl": "https://pypi.org",
      "identifier": "mcp-arabic-toolkit",
      "version": "0.2.0",
      "transport": { "type": "stdio" }
    }
  ]
}
```

The server name uses the `io.github.<owner>/<repo>` namespace, which the
registry verifies against GitHub ownership during publish.

### Steps

1. **Build and publish the PyPI package** so the registry has something to point
   at:
   ```bash
   python -m build
   twine upload dist/*
   ```
2. **Install the registry publisher CLI** (`mcp-publisher`) — see the
   [registry publishing guide](https://github.com/modelcontextprotocol/registry/blob/main/docs/guides/publishing/publish-server.md).
3. **Authenticate** with GitHub so the CLI can verify the `io.github.*`
   namespace:
   ```bash
   mcp-publisher login github
   ```
4. **Publish** from the directory containing `server.json`:
   ```bash
   mcp-publisher publish
   ```

To list this server on the community **modelcontextprotocol/servers** README as
well, see [SUBMISSION.md](SUBMISSION.md) for the exact entry text and PR steps.

## License

MIT — see [LICENSE](LICENSE).