# TablaFocusMCP

[![CI](https://github.com/sreeramkongeseri/TablaFocusMCP/actions/workflows/ci.yml/badge.svg)](https://github.com/sreeramkongeseri/TablaFocusMCP/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/sreeramkongeseri/TablaFocusMCP?sort=semver)](https://github.com/sreeramkongeseri/TablaFocusMCP/releases)
[![License](https://img.shields.io/github/license/sreeramkongeseri/TablaFocusMCP)](LICENSE)

TablaFocusMCP is a MCP server focused on tabla learning workflows.
It unifies glossary and bol-lexicon lookup, composition design and validation, certification preparation, practice planning, taal explanation, the Sadhana Path skill tree, daily practice missions, a bol phrase library, and the Year in Tabla calendar into one consistent interface for AI assistants and learners at any stage.
It also covers the tabla lineage (parampara) graph, an annotated listening room, instrument anatomy, tabla math drills, layakari training, and export of compositions as `.tabla` documents the Tabla Focus iOS app imports directly.
Alongside tools, it also exposes MCP resources (readable datasets) and prompts (guided workflows).

<p align="center">
  <img src="assets/tablafocus-mcp-icon.png" alt="TablaFocusMCP icon" width="420" />
</p>

## How To Use

Once `tablafocus` is installed in your MCP client, chat naturally about what you want to practice or build.
The assistant can explain taals, generate compositions, create quizzes/mocks, and plan practice weeks.

Try prompts like these:

1. `Explain teental for a beginner, including vibhag structure, sam, and khali.`
2. `Generate a valid 1-cycle tihai in teental (chatusra) and show the beat-by-beat mapping.`
3. `Create a weekly tabla practice plan for 45 minutes/day, 5 days/week, focused on clarity and layakari.`
4. `Build a 15-question ABGMVM Madhyama Pratham mock test with answer key and short rationales.`
5. `I have a tihai idea for teental. Help me refine it so it resolves cleanly to sam in 1 cycle.`
6. `Transpose this teental tihai into rupak while preserving the structural feel as closely as possible.`
7. `I have F7 and F8 performance-ready and I'm practicing I1 on the Sadhana Path — what should I work on next?`
8. `Show me beginner Delhi-gharana bol phrases I can use in a teental kaida, with tempo targets.`
9. `Give me today's tabla daily mission.`
10. `What happened in the tabla world in January, and share a "did you know?" fact about the bayan.`
11. `Trace Ustad Alla Rakha's teacher chain and student tree in the lineage graph.`
12. `Plan three listening sessions of archive-era solo recordings from the Punjab gharana, with notes on what to listen for.`
13. `Build a 1-cycle chakradhar in teental and export it as a .tabla file I can import into the Tabla Focus app.`
14. `Explain the parts of the bayan and how shell material changes the sound.`

Workflow prompt templates are also available:

| Prompt name              | What it guides                                                                      | Inputs                                                                                                                  |
| ------------------------ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `cert_prep_plan`         | Certification workflow (`catalog` -> `mock` -> `plan`)                              | `board`, `certification_level`, `days_per_week`, `minutes_per_day`                                                      |
| `weekly_practice_reset`  | Weekly reset workflow after missed sessions or fatigue                              | `goals` (semicolon-delimited), `daily_minutes`, `days_per_week`, optional `missed_days`, `completed_minutes`, `fatigue` |
| `exam_week_plan`         | Focused 7-day exam prep workflow                                                    | `board`, `certification_level`, `daily_minutes`, optional `weak_areas`, `fatigue`                                       |
| `missed_week_recovery`   | Recovery workflow after a disrupted practice week                                   | `goals` (semicolon-delimited), `daily_minutes`, `days_per_week`, optional `missed_days`, `completed_minutes`, `fatigue` |
| `composition_polish`     | Iterative composition draft -> validate -> refine flow                              | `taal`, `form`, `jati`, optional `cycles`, optional `polish_rounds`                                                     |
| `gharana_listening_tour` | Lineage-guided listening course (`lineage_explorer` -> `listening_room`)            | `gharana`, optional `sessions` (default 5)                                                                              |
| `today_in_tabla`         | Morning brief from calendar events, today-in-history, one fact, and a daily mission | `date` (`YYYY-MM-DD`, optional)                                                                                         |

## Core Tools

All tools return a common envelope with `meta` and `data`.

Identifier compatibility with the Tabla Focus iOS app: taal inputs accept MCP slug ids (`teental`), display-name variants (`Teen Taal`, `Roopak`, `Dadra taal`), and the app's catalog UUIDs (`app_tala_id`); glossary term search also matches the app's glossary id slugs; and composition `form` accepts the app spelling `chakradar` for the canonical `chakradhar`.

| Tool                     | What it does                                                   | Required inputs                                                                | Optional inputs                                                                                                                                                                                                                                               | Output highlights                                                                                                                                                                 |
| ------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `glossary_lookup`        | Finds glossary terms, bol lexicon strokes, and vocab spellings | None                                                                           | `term`, `category`, `source` (`glossary`\|`bol_lexicon`\|`vocab`\|`all`), `limit` (1-100)                                                                                                                                                                     | Glossary entries plus bol results (devanagari, hand, resonance, stroke family, aliases) and vocab results                                                                         |
| `compose_builder`        | Builds mathematically valid compositions                       | `taal`, `form`, `jati` (`tisra`\|`chatusra`\|`khanda`\|`misra`)                | `cycles` (1-12), `include_app_export` (attach a `.tabla` app-import document)                                                                                                                                                                                 | Composition equation, parameters, timeline segments, alternatives                                                                                                                 |
| `composition_transposer` | Transposes a valid composition into a new taal/jati context    | `source` (taal, form, jati, cycles, composition_input), `target` (taal, jati)  | `target.cycles`, `preserve_mode=shape_ratio`, `include_app_export` (attach a `.tabla` app-import document for the target)                                                                                                                                     | Chosen transposed composition, scale factor, preservation report, alternatives, warnings                                                                                          |
| `certification_catalog`  | Lists certification tracks and level breakdowns                | None                                                                           | `board`, `certification_level`                                                                                                                                                                                                                                | Board/level catalog with papers, categories, objectives, references                                                                                                               |
| `assessment_builder`     | Creates quizzes and certification mocks                        | `mode` (`practice_quiz`\|`cert_mock`)                                          | `count` (1-100, default 10), `seed`, `board`, `certification_level`, `taal`                                                                                                                                                                                   | Questions, answer key with rationale, rubric, optional certification reference                                                                                                    |
| `practice_coach`         | Generates adaptive weekly practice plans                       | `goals` (array), `availability` (object)                                       | `profile_id`, `availability.daily_minutes` (1-600), `availability.weekly_minutes` (1-4000), `availability.days_per_week` (1-7), `week_context.missed_days` (0-7), `week_context.completed_minutes` (0-4000), `week_context.fatigue` (`low`\|`medium`\|`high`) | Weekly target, daily targets, per-day sessions, adaptive adjustments                                                                                                              |
| `taal_catalog`           | Returns full catalog or one taal detail                        | None                                                                           | `taal_id`                                                                                                                                                                                                                                                     | Taal structure, vibhag, sam/khali, clap-wave, counting guidance, theka                                                                                                            |
| `composition_validator`  | Validates composition equation and timeline checks             | `taal`, `form`, `jati`, `cycles` (1-12), `composition_input`                   | `composition_input.P`, `G`, `M`, `g`, optional detailed `segments`                                                                                                                                                                                            | `is_valid`, failure reasons, equation/timeline/segment checks                                                                                                                     |
| `explain_taal`           | Compatibility alias for taal explanation                       | `taal`                                                                         | None                                                                                                                                                                                                                                                          | Explanation payload sourced from canonical `taal_catalog` data                                                                                                                    |
| `phrase_library`         | Looks up tabla bol phrases (kaida/rela/laggi building blocks)  | None                                                                           | `query`, `tala`, `gharana`, `usage_tag`, `difficulty` (`beginner`\|`intermediate`\|`advanced`), `limit` (1-100)                                                                                                                                               | Matching phrases with notation, tempo star ladder, teaching notes; facet lists                                                                                                    |
| `skill_path`             | Returns the Sadhana Path skill tree and derives learner state  | None                                                                           | `performance_ready` (skill ids), `practicing` (skill ids), `section`, `skill_id`, `recommend_limit` (1-20)                                                                                                                                                    | Per-skill state (locked/available/practicing/performance-ready), next-step suggestions, milestone progress                                                                        |
| `daily_mission`          | Generates a deterministic daily practice mission               | None                                                                           | `sequence` (default 1), `date` (`YYYY-MM-DD`), `kind` (`creator`\|`quiz_lightning`\|`tabla_math`\|`practice_tala`)                                                                                                                                            | Rotating mission with target, prompt, rotation metadata                                                                                                                           |
| `tabla_calendar`         | Browses the Year in Tabla calendar and lore                    | None                                                                           | `mode` (`events`\|`festivals`\|`did_you_know`\|`today_history`), `month`, `day`, `category`, `topic`, `year`, `query`, `limit`                                                                                                                                | Anniversary/festival events, recurring festivals, "Did you know?" facts, or dated today-in-history entries                                                                        |
| `lineage_explorer`       | Explores the parampara (lineage) graph                         | None                                                                           | `person` (fuzzy), `gharana`, `direction` (`teachers`\|`students`\|`both`), `depth` (1-5), `limit`                                                                                                                                                             | Person match with teacher chain and student tree (edge relation/confidence/verified flags), gharana summaries, cross-links into listening_room/creators, nearest-name suggestions |
| `listening_room`         | Recommends recordings from the annotated discography           | None                                                                           | `query`, `artist`, `gharana`, `era`, `setting`, `kind` (`album`\|`track`), `featured_only`, `limit` (default 10)                                                                                                                                              | Recordings with artist/gharana joins, curator notes, listen-for pointers; era/setting/gharana facet lists                                                                         |
| `tabla_anatomy`          | Explores tabla parts and materials                             | None                                                                           | `part` (fuzzy), `instrument` (`dayan`\|`bayan`), `limit`                                                                                                                                                                                                      | Part captions and regional names, material options with relative trait profiles, full parts index                                                                                 |
| `tabla_math`             | Generates verified tabla arithmetic drills                     | None                                                                           | `taal`, `jati`, `difficulty` (`beginner`\|`intermediate`\|`advanced`), `count` (1-20, default 5), `seed`                                                                                                                                                      | Tihai/tukra/chakradhar, matra-counting, jati-conversion, and dha-position problems with worked, engine-verified solutions; deterministic per seed                                 |
| `layakari_trainer`       | Generates layakari (laya ratio) exercises                      | `taal`                                                                         | `ratios` (barabar/dugun/tigun/chaugun/aad/kuad/biad or `1:1`-style labels), `difficulty`, `count` (1-20), `seed`                                                                                                                                              | Per-beat theka alignment tables at each ratio, eligible tempo bands with progression, realignment notes; deterministic per seed                                                   |
| `notation_exporter`      | Exports a composition as a Tabla Focus `.tabla` app document   | `taal`, plus either `form` + `jati` + `cycles` + `composition_input` or `bols` | `title`, `notes`                                                                                                                                                                                                                                              | `app_export` (NotationEnvelope v1 JSON the iOS app imports via Files/AirDrop/share), format descriptor with suggested filename, honest import instructions, content summary       |

## How To Install

Run directly from npm:

```bash
npx -y tablafocus-mcp@latest
```

Codex CLI:

```bash
codex mcp add tablafocus -- npx -y tablafocus-mcp@latest
```

Claude Code:

```bash
claude mcp add -s user tablafocus -- npx -y tablafocus-mcp@latest
```

JSON-based clients (Claude Desktop, Cline, VS Code Copilot):

```json
{
  "mcpServers": {
    "tablafocus": {
      "command": "npx",
      "args": ["-y", "tablafocus-mcp@latest"]
    }
  }
}
```

Cursor:

```json
{
  "name": "tablafocus",
  "command": "npx",
  "args": ["-y", "tablafocus-mcp@latest"]
}
```

## Documentation

- [Client setup](docs/mcp/client-setup.md)
- [MCP reference](docs/mcp/reference.md)
- [Changelog](CHANGELOG.md)
- [Contributing guide](.github/CONTRIBUTING.md)
- [Roadmap](docs/ROADMAP.md)
- [MIT License](LICENSE)