MCP Grammar Tools
Allows generating text using OpenAI models constrained by a grammar, using the OpenAI Responses API with custom tool grammar format.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Grammar Tools Validate this grammar: start: 'hello' 'world'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Grammar Tools
MCP server for validating and testing llguidance grammars (Lark format). Provides grammar validation, batch test execution, and syntax documentation — ideal for iteratively building grammars with AI coding assistants.
Installation
With uvx (recommended)
uvx guidance-lark-mcpWith pip
pip install guidance-lark-mcpFrom source
cd mcp-grammar-tools
pip install -e .Related MCP server: Fast Mermaid Validator MCP
MCP Client Configuration
GitHub Copilot CLI
You can add the server using the interactive /mcp add command or by editing the config file directly. See the Copilot CLI MCP documentation for full details.
Option 1: Interactive setup
In the Copilot CLI, run /mcp add, select Local/STDIO, and enter uvx guidance-lark-mcp as the command.
Option 2: Edit config file
Add the following to ~/.copilot/mcp-config.json:
{
"mcpServers": {
"grammar-tools": {
"type": "local",
"command": "uvx",
"args": ["guidance-lark-mcp"],
"tools": ["*"]
}
}
}This gives you grammar validation and batch testing out of the box. To also enable LLM-powered generation (generate_with_grammar), add ENABLE_GENERATION and your credentials to env:
"env": {
"ENABLE_GENERATION": "true",
"OPENAI_API_KEY": "your-key-here"
}For Azure OpenAI (with Entra ID via az login), use guidance-lark-mcp[azure] and set the endpoint instead:
"args": ["guidance-lark-mcp[azure]"],
"env": {
"ENABLE_GENERATION": "true",
"AZURE_OPENAI_ENDPOINT": "https://your-resource.openai.azure.com/",
"OPENAI_MODEL": "your-deployment-name"
}See Backend Configuration for all supported backends.
After saving, use /mcp show to verify the server is connected.
VS Code
{
"mcpServers": {
"grammar-tools": {
"type": "local",
"command": "uvx",
"args": ["guidance-lark-mcp"],
"env": {
"ENABLE_GENERATION": "true",
"OPENAI_API_KEY": "your-key-here"
},
"tools": ["*"]
}
}
}Claude Desktop
{
"mcpServers": {
"grammar-tools": {
"command": "uvx",
"args": ["guidance-lark-mcp"],
"env": {
"ENABLE_GENERATION": "true",
"OPENAI_API_KEY": "your-key-here"
}
}
}
}Usage
Available Tools
validate_grammar— Validate grammar completeness and consistency using llguidance's built-in validator.{"grammar": "start: \"hello\" \"world\""}run_batch_validation_tests— Run batch validation tests from a JSON file against a grammar. Returns pass/fail statistics and detailed failure info.{ "grammar": "start: /[0-9]+/", "test_file": "tests.json" }Test file format:
[ {"input": "123", "should_parse": true, "description": "Valid number"}, {"input": "abc", "should_parse": false, "description": "Not a number"} ]get_llguidance_documentation— Fetch the llguidance grammar syntax documentation from the official repo.generate_with_grammar(optional, requiresENABLE_GENERATION=true) — Generate text using an OpenAI model constrained by a grammar. Uses the Responses API with custom tool grammar format, so output is guaranteed to conform to the grammar. RequiresOPENAI_API_KEYenvironment variable. See Backend Configuration for Azure and other endpoints.
Backend Configuration
The generate_with_grammar tool uses the OpenAI Python SDK, which natively supports multiple backends via environment variables:
Backend | Required env vars | Optional env vars |
OpenAI (default) |
|
|
Azure OpenAI (API key) |
|
|
Azure OpenAI (Entra ID) |
|
|
Custom endpoint |
|
|
The server auto-detects which backend to use:
If
AZURE_OPENAI_ENDPOINTis set → usesAzureOpenAIclient (with Entra ID or API key)Otherwise → uses
OpenAIclient (readsOPENAI_API_KEYandOPENAI_BASE_URLautomatically)
The server logs which backend it detects on startup.
Example: Azure OpenAI (API key)
{
"mcpServers": {
"grammar-tools": {
"type": "local",
"command": "uvx",
"args": ["guidance-lark-mcp"],
"env": {
"ENABLE_GENERATION": "true",
"AZURE_OPENAI_ENDPOINT": "https://my-resource.openai.azure.com",
"AZURE_OPENAI_API_KEY": "your-azure-key",
"OPENAI_MODEL": "gpt-4.1"
},
"tools": ["*"]
}
}
}Example: Azure OpenAI (Entra ID / keyless)
Requires az login and the azure extra: pip install guidance-lark-mcp[azure]
{
"mcpServers": {
"grammar-tools": {
"type": "local",
"command": "uvx",
"args": ["guidance-lark-mcp[azure]"],
"env": {
"ENABLE_GENERATION": "true",
"AZURE_OPENAI_ENDPOINT": "https://my-resource.openai.azure.com",
"OPENAI_MODEL": "gpt-4.1"
},
"tools": ["*"]
}
}
}Example Workflow
Build a grammar iteratively with an AI assistant:
Start with the spec — paste EBNF rules from a language specification
Write a basic grammar — translate a few rules to Lark format
Validate — use
validate_grammarto check for missing rulesWrite tests — create a JSON test file with sample inputs
Batch test — use
run_batch_validation_teststo find failuresFix & repeat — refine the grammar until all tests pass
Example Grammars
The examples/ directory includes sample grammars built using these tools, with Lark grammar files, test suites, and documentation:
GraphQL — executable subset of the GraphQL spec (queries, mutations, fragments, variables)
Troubleshooting
Server fails to connect in Copilot CLI / VS Code?
MCP clients like Copilot CLI only show "Connection closed" when a server crashes on startup. To see the actual error, run the server directly in your terminal:
uvx guidance-lark-mcpOr with generation enabled:
ENABLE_GENERATION=true OPENAI_API_KEY=your-key uvx guidance-lark-mcpCommon issues:
Missing credentials —
ENABLE_GENERATION=truewithout a validOPENAI_API_KEYorAZURE_OPENAI_ENDPOINT. The server will still start and serve validation tools;generate_with_grammarwill return a descriptive error.Azure Entra ID — make sure you've run
az loginand are usingguidance-lark-mcp[azure](not the base package).Slow first start —
uvxneeds to resolve and install dependencies on first run, which may exceed the MCP client's connection timeout. Runuvx guidance-lark-mcponce manually to warm the cache.Updating to a new version —
uvxcaches packages, so after a new release you may need to clear the cache and restart your MCP client:uv cache clean guidance-lark-mcp
Development
git clone https://github.com/guidance-ai/guidance-lark-mcp
cd guidance-lark-mcp
uv sync
uv run pytest tests/ -qAvailable Tools
3 toolsget_llguidance_documentationA
Fetch the llguidance grammar syntax documentation.
Inputs: no named parameters.
run_batch_validation_testsA
Run batch validation tests from a JSON file against an llguidance grammar. Test file should contain array of {input, should_parse, description?} objects. Returns high-level statistics (total, passed, failed, success_rate) and detailed information for failed tests.
Inputs: grammar (required), test_file (required).
validate_grammarA
Validate llguidance grammar completeness and consistency using llguidance's built-in validator. Returns validation result with any errors or warnings.
Inputs: grammar (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a distinct purpose: documentation retrieval, batch testing, and grammar validation. There is no overlap or ambiguity.
All tool names follow a consistent verb_noun pattern (get_, run_, validate_) with clear and descriptive names.
Three tools is appropriate for a focused grammar validation and testing server, covering the core functionalities without being overly sparse.
The server covers documentation retrieval, validation, and batch testing. A minor gap is the lack of grammar editing or listing tools, but the core use case is well supported.
Maintenance
Related MCP Connectors
Deterministic validation for AI-generated artifacts: JSON Schema, OpenAPI response, SQL syntax.
Convert, lint and generate LLM tool schemas for OpenAI, Anthropic, Gemini and MCP
Create, validate and audit llms.txt, incl. the Lighthouse Agentic Browsing check.
Validate oh-my-posh configurations and segment snippets against the official schema.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides access to up-to-date Ilograph documentation and syntax validation capabilities.113MIT
- AlicenseNot gradedqualityDmaintenanceValidates Mermaid diagrams with comprehensive grammar parsing supporting 28+ diagram types. Processes markdown files, ZIP archives, and direct input with detailed error reporting and enterprise-grade performance capabilities.235 npm3Apache 2.0
- AlicenseBqualityDmaintenanceA tool for validating Mermaid diagram syntax through CLI and MCP interfaces, providing real-time error checking and line-specific feedback. It enables AI assistants to self-validate and debug generated diagrams across all Mermaid types, ensuring valid visual documentation.115 npm2MIT
- AlicenseAqualityDmaintenanceHelps AI agents author, validate, explain, draft, and test Liminate Agreements locally, with an optional API for translating compliance documents into Agreement drafts.6Apache 2.0