# ipa-tutor

Score a Koine Greek reading. Agents start at `POST /mcp` (MCP Streamable HTTP, no SSE). Tools: `score`, `heard_as`, `recognize`, `create_upload`. `score_attempt` is an alias of `score`.

`score` takes a Greek `target` plus `ipa`, a small `audio_base64` WAV, or `audio_url`. `ipa` wins when it is also sent. The response is `tutor-v1` JSON. `proximity` runs from 0 to 1. For λόγος heard as `l o g o s` it is 1.0. `heard_as` returns that ranking only and does not change `proximity`. `recognize` turns WAV bytes into phones and does not score. Chat, Claude, and Gemini pass JSON. They do not attach a microphone.

The JSON names each sound, a feature diff, an error code, stress, and a ranked `heard_as` list. It does not include a pronunciation tip.

Public host: [https://ipa.raymati.com](https://ipa.raymati.com). Local IPA scoring: `http://127.0.0.1:43117`.

## For agents

- [Install](/docs/install.md) has the client snippets
- [llms.txt](/llms.txt) is the index
- [OpenAPI 3.1](/openapi.json) has the operations, schemas, and scored examples
- [MCP server.json](/server.json) is `com.raymati/ipa` at `/mcp`. [/server-card.json](/server-card.json) is the same document
- [Agent card](/.well-known/agent-card.json) is the A2A discovery file. This host speaks MCP, not an A2A task API
- [Registries](/docs/registries.md) and [Submitting](/docs/submitting.md) are the steps after deploy. This repo does not submit

An HTML page also answers `Accept: text/markdown` with its Markdown sibling. That negotiation is a draft. The `.md` URL stays available either way.

## Read next

- [Quickstart](/docs/quickstart.md) has curl, Python, JavaScript, and Rust
- [Install](/docs/install.md) connects ChatGPT, Claude, Cursor, VS Code, Gemini CLI, and Claude Code
- [Concepts](/docs/concepts.md) defines proximity, status, stress, and heard_as
- [Errors](/docs/errors.md) is RFC 9457 plus the rate-limit headers
- [Reference](/docs/reference.md) is the schema, field by field
- [Changelog](/docs/changelog.md)