Installation

MCParser needs Python 3.11 or later.

pip install --pre mcparser      # alpha release; or: uv tool install --prerelease allow mcparser
export ANTHROPIC_API_KEY=...    # the default models are Anthropic's

From a clone of the repository: uv sync, then prefix the commands below with uv run. Other model providers (OpenAI, Google, Bedrock, Groq, Mistral, xAI, OpenRouter) are installed with extras, for example pip install "mcparser[openai]". See Models and providers.

Quick start

# 1. Raw text (one sentence per line, or YAML with 'text' fields) -> CoNLL-U with a frequency baseline
mcparser init input.txt -o pred.conllu -s ud-train.conllu

# 2. Try one sentence first to see what it costs
mcparser run pred.conllu -s ud-train.conllu --sentence SENT_ID --rounds 1

# 3. Annotate everything, stopping at a spending limit (run again to continue)
mcparser run pred.conllu -s ud-train.conllu --rounds 3 --max-cost 20

# 4. Compare with gold annotation using the CoNLL 2018 metrics
mcparser evaluate pred.conllu gold.conllu

-s names the trusted CoNLL-U files (read-only examples). The prediction file is edited in place and every run can be resumed. mcparser settings prints all settings (models for each role, confidence threshold, rounds, batch sizes, cost limit).

How well does it work?

On 100 held-out Ancient Greek (PROIEL) dev sentences, annotated from raw tokens with the default models (Opus 5.5 for segmentation, lemma and syntax, Sonnet 5.5 for UPOS, FEATS and scoring, Haiku 5.5 for XPOS) in two rounds, scored by the official CoNLL 2018 script’s metrics:

The run cost about $7.80 ($0.078 per sentence, $0.006 per word). Cost per sentence depends on language and length; it is roughly $0.03 to $0.12 with Sonnet for the strong roles and one round. Differences of about 1.5 points on a hundred sentences are noise. Results on four complete dev files, the cost breakdown and the caveats are in Results.

Using it from Claude Desktop

mcparser mcp config -s train=ud-train.conllu -s pred=pred.conllu:rw

prints the mcpServers entry to add to claude_desktop_config.json. Sources are [NAME=]PATH[:ro|rw[:CONFIDENCE]]: read-only sources hold trusted examples and writable sources hold predictions. mcparser mcp serve runs the server directly (stdio or streamable HTTP; --read-only removes the editing tools).

From Python

import anyio
from mcparser.agents.team import AgentTeam
from mcparser.corpus import CorpusStore
from mcparser.pipeline import Pipeline
from mcparser.settings import Settings

store = CorpusStore()
store.add_source("train", "train.conllu")
store.add_source("pred", "pred.conllu", mode="rw")
settings = Settings(rounds=2, max_cost=20)
team = AgentTeam(store, "pred", settings)
report = anyio.run(Pipeline(store, "pred", team, settings).run)

The corpus store (search, validation, editing, confidence) is also usable without any agents or model. See the API reference.

Limitations

• LLM output varies from run to run, and the agents inherit the treebank’s own inconsistencies. Check a sample of the output before relying on it, and use the confidence scores to decide what to review by hand.

• Cost grows with the number of words, and long sentences are expensive. Use --max-sentences, --sentence and --max-cost while you tune a setup.

• Only the Anthropic models have been tested in real runs. Other providers are supported through pydantic-ai but are untested here.

• The tokeniser in init is simple (whitespace and punctuation). Clitics and multiword tokens are left to the segmentation agent.

Documentation

Full documentation: https://rbturnbull.github.io/mcparser (build it locally with uv run --group docs sphinx-build -W docs docs/_build/html). Design notes for contributors are in AGENTS.md, and changes in CHANGELOG.md.

Contributing

uv sync --all-groups
uv run pytest        # the tests never call a model; 100% line and branch coverage is required

See CONTRIBUTING.md. Please report bugs and ideas on the issue tracker.

Licence

Apache 2.0, see LICENSE. The vendored CoNLL 2018 evaluation script in tests/official/ is under the Mozilla Public Licence 2.0.