{
  "markdown": "# MCP Grammar Tools\n\n<!-- mcp-name: io.github.guidance-ai/guidance-lark-mcp -->\n\nMCP server for validating and testing [llguidance](https://github.com/guidance-ai/llguidance) grammars (Lark format). Provides grammar validation, batch test execution, and syntax documentation — ideal for iteratively building grammars with AI coding assistants.\n\n## Installation\n\n### With uvx (recommended)\n```bash\nuvx guidance-lark-mcp\n```\n\n### With pip\n```bash\npip install guidance-lark-mcp\n```\n\n### From source\n```bash\ncd mcp-grammar-tools\npip install -e .\n```\n\n## MCP Client Configuration\n\n### GitHub Copilot CLI\n\nYou can add the server using the interactive `/mcp add` command or by editing the config file directly. See the [Copilot CLI MCP documentation](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) for full details.\n\n**Option 1: Interactive setup**\n\nIn the Copilot CLI, run `/mcp add`, select **Local/STDIO**, and enter `uvx guidance-lark-mcp` as the command.\n\n**Option 2: Edit config file**\n\nAdd the following to `~/.copilot/mcp-config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"grammar-tools\": {\n      \"type\": \"local\",\n      \"command\": \"uvx\",\n      \"args\": [\"guidance-lark-mcp\"],\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\nThis 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`:\n\n```json\n\"env\": {\n  \"ENABLE_GENERATION\": \"true\",\n  \"OPENAI_API_KEY\": \"your-key-here\"\n}\n```\n\nFor Azure OpenAI (with Entra ID via `az login`), use `guidance-lark-mcp[azure]` and set the endpoint instead:\n\n```json\n\"args\": [\"guidance-lark-mcp[azure]\"],\n\"env\": {\n  \"ENABLE_GENERATION\": \"true\",\n  \"AZURE_OPENAI_ENDPOINT\": \"https://your-resource.openai.azure.com/\",\n  \"OPENAI_MODEL\": \"your-deployment-name\"\n}\n```\n\nSee [Backend Configuration](#backend-configuration) for all supported backends.\n\nAfter saving, use `/mcp show` to verify the server is connected.\n\n### VS Code\n\n```json\n{\n  \"mcpServers\": {\n    \"grammar-tools\": {\n      \"type\": \"local\",\n      \"command\": \"uvx\",\n      \"args\": [\"guidance-lark-mcp\"],\n      \"env\": {\n        \"ENABLE_GENERATION\": \"true\",\n        \"OPENAI_API_KEY\": \"your-key-here\"\n      },\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\n### Claude Desktop\n```json\n{\n  \"mcpServers\": {\n    \"grammar-tools\": {\n      \"command\": \"uvx\",\n      \"args\": [\"guidance-lark-mcp\"],\n      \"env\": {\n        \"ENABLE_GENERATION\": \"true\",\n        \"OPENAI_API_KEY\": \"your-key-here\"\n      }\n    }\n  }\n}\n```\n\n## Usage\n\n### Available Tools\n\n1. **`validate_grammar`** — Validate grammar completeness and consistency using llguidance's built-in validator.\n   ```json\n   {\"grammar\": \"start: \\\"hello\\\" \\\"world\\\"\"}\n   ```\n\n2. **`run_batch_validation_tests`** — Run batch validation tests from a JSON file against a grammar. Returns pass/fail statistics and detailed failure info.\n   ```json\n   {\n     \"grammar\": \"start: /[0-9]+/\",\n     \"test_file\": \"tests.json\"\n   }\n   ```\n\n   Test file format:\n   ```json\n   [\n     {\"input\": \"123\", \"should_parse\": true, \"description\": \"Valid number\"},\n     {\"input\": \"abc\", \"should_parse\": false, \"description\": \"Not a number\"}\n   ]\n   ```\n\n3. **`get_llguidance_documentation`** — Fetch the llguidance grammar syntax documentation from the official repo.\n\n4. **`generate_with_grammar`** *(optional, requires `ENABLE_GENERATION=true`)* — Generate text using an OpenAI model constrained by a grammar. Uses the [Responses API with custom tool grammar format](https://developers.openai.com/api/docs/guides/function-calling/#context-free-grammars), so output is guaranteed to conform to the grammar. Requires `OPENAI_API_KEY` environment variable. See [Backend Configuration](#backend-configuration) for Azure and other endpoints.\n\n## Backend Configuration\n\nThe `generate_with_grammar` tool uses the OpenAI Python SDK, which natively supports multiple backends via environment variables:\n\n| Backend | Required env vars | Optional env vars |\n|---------|-------------------|-------------------|\n| **OpenAI** (default) | `OPENAI_API_KEY` | `OPENAI_MODEL` |\n| **Azure OpenAI (API key)** | `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY` | `AZURE_OPENAI_API_VERSION`, `OPENAI_MODEL` |\n| **Azure OpenAI (Entra ID)** | `AZURE_OPENAI_ENDPOINT` + `az login` | `AZURE_OPENAI_API_VERSION`, `OPENAI_MODEL` |\n| **Custom endpoint** | `OPENAI_API_KEY`, `OPENAI_BASE_URL` | `OPENAI_MODEL` |\n\nThe server auto-detects which backend to use:\n- If `AZURE_OPENAI_ENDPOINT` is set → uses `AzureOpenAI` client (with Entra ID or API key)\n- Otherwise → uses `OpenAI` client (reads `OPENAI_API_KEY` and `OPENAI_BASE_URL` automatically)\n\nThe server logs which backend it detects on startup.\n\n### Example: Azure OpenAI (API key)\n```json\n{\n  \"mcpServers\": {\n    \"grammar-tools\": {\n      \"type\": \"local\",\n      \"command\": \"uvx\",\n      \"args\": [\"guidance-lark-mcp\"],\n      \"env\": {\n        \"ENABLE_GENERATION\": \"true\",\n        \"AZURE_OPENAI_ENDPOINT\": \"https://my-resource.openai.azure.com\",\n        \"AZURE_OPENAI_API_KEY\": \"your-azure-key\",\n        \"OPENAI_MODEL\": \"gpt-4.1\"\n      },\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\n### Example: Azure OpenAI (Entra ID / keyless)\n\nRequires `az login` and the `azure` extra: `pip install guidance-lark-mcp[azure]`\n\n```json\n{\n  \"mcpServers\": {\n    \"grammar-tools\": {\n      \"type\": \"local\",\n      \"command\": \"uvx\",\n      \"args\": [\"guidance-lark-mcp[azure]\"],\n      \"env\": {\n        \"ENABLE_GENERATION\": \"true\",\n        \"AZURE_OPENAI_ENDPOINT\": \"https://my-resource.openai.azure.com\",\n        \"OPENAI_MODEL\": \"gpt-4.1\"\n      },\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\n## Example Workflow\n\nBuild a grammar iteratively with an AI assistant:\n\n1. **Start with the spec** — paste EBNF rules from a language specification\n2. **Write a basic grammar** — translate a few rules to Lark format\n3. **Validate** — use `validate_grammar` to check for missing rules\n4. **Write tests** — create a JSON test file with sample inputs\n5. **Batch test** — use `run_batch_validation_tests` to find failures\n6. **Fix & repeat** — refine the grammar until all tests pass\n\n## Example Grammars\n\nThe `examples/` directory includes sample grammars built using these tools, with Lark grammar files, test suites, and documentation:\n\n- **[GraphQL](examples/graphql/)** — executable subset of the GraphQL spec (queries, mutations, fragments, variables)\n\n## Troubleshooting\n\n**Server fails to connect in Copilot CLI / VS Code?**\n\nMCP 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:\n\n```bash\nuvx guidance-lark-mcp\n```\n\nOr with generation enabled:\n\n```bash\nENABLE_GENERATION=true OPENAI_API_KEY=your-key uvx guidance-lark-mcp\n```\n\nCommon issues:\n- **Missing credentials** — `ENABLE_GENERATION=true` without a valid `OPENAI_API_KEY` or `AZURE_OPENAI_ENDPOINT`. The server will still start and serve validation tools; `generate_with_grammar` will return a descriptive error.\n- **Azure Entra ID** — make sure you've run `az login` and are using `guidance-lark-mcp[azure]` (not the base package).\n- **Slow first start** — `uvx` needs to resolve and install dependencies on first run, which may exceed the MCP client's connection timeout. Run `uvx guidance-lark-mcp` once manually to warm the cache.\n- **Updating to a new version** — `uvx` caches packages, so after a new release you may need to clear the cache and restart your MCP client:\n  ```bash\n  uv cache clean guidance-lark-mcp\n  ```\n\n## Development\n\n```bash\ngit clone https://github.com/guidance-ai/guidance-lark-mcp\ncd guidance-lark-mcp\nuv sync\nuv run pytest tests/ -q\n```\n\n",
  "bytes": 7656,
  "sha": "92bfa9fcd9410de27936134f981b98389a1172b1ed5fba2fe68e2b0f7b35c06d",
  "repo_slug": "guidance-ai/guidance-lark-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_guidance_ai_guidance_lark_mcp_89a2e75e/readme"
}