Metadata-Version: 2.4
Name: guidance-lark-mcp
Version: 0.1.0
Summary: MCP server for validating and testing llguidance grammars (Lark format)
License-Expression: MIT
Project-URL: Homepage, https://github.com/guidance-ai/guidance-lark-mcp
Project-URL: Repository, https://github.com/guidance-ai/guidance-lark-mcp.git
Project-URL: Issues, https://github.com/guidance-ai/guidance-lark-mcp/issues
Keywords: mcp,model-context-protocol,llguidance,grammar,lark,parser
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lark>=1.3.0
Requires-Dist: llguidance>=1.2.0
Requires-Dist: mcp>=1.17.0
Requires-Dist: openai>=1.70.0
Requires-Dist: requests>=2.32.5
Provides-Extra: azure
Requires-Dist: azure-identity>=1.16.0; extra == "azure"
Dynamic: license-file

# MCP Grammar Tools

<!-- mcp-name: io.github.guidance-ai/guidance-lark-mcp -->

MCP 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.

## Installation

### With uvx (recommended)
```bash
uvx guidance-lark-mcp
```

### With pip
```bash
pip install guidance-lark-mcp
```

### From source
```bash
cd mcp-grammar-tools
pip install -e .
```

## MCP Client Configuration

### VS Code / Copilot CLI (`~/.copilot/mcp-config.json`)
```json
{
  "mcpServers": {
    "grammar-tools": {
      "type": "local",
      "command": "uvx",
      "args": ["guidance-lark-mcp"],
      "env": {
        "ENABLE_GENERATION": "true",
        "OPENAI_API_KEY": "your-key-here"
      },
      "tools": ["*"]
    }
  }
}
```

### Claude Desktop
```json
{
  "mcpServers": {
    "grammar-tools": {
      "command": "uvx",
      "args": ["guidance-lark-mcp"],
      "env": {
        "ENABLE_GENERATION": "true",
        "OPENAI_API_KEY": "your-key-here"
      }
    }
  }
}
```

## Usage

### Available Tools

1. **`validate_grammar`** — Validate grammar completeness and consistency using llguidance's built-in validator.
   ```json
   {"grammar": "start: \"hello\" \"world\""}
   ```

2. **`run_batch_validation_tests`** — Run batch validation tests from a JSON file against a grammar. Returns pass/fail statistics and detailed failure info.
   ```json
   {
     "grammar": "start: /[0-9]+/",
     "test_file": "tests.json"
   }
   ```

   Test file format:
   ```json
   [
     {"input": "123", "should_parse": true, "description": "Valid number"},
     {"input": "abc", "should_parse": false, "description": "Not a number"}
   ]
   ```

3. **`get_llguidance_documentation`** — Fetch the llguidance grammar syntax documentation from the official repo.

4. **`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.

## 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) | `OPENAI_API_KEY` | `OPENAI_MODEL` |
| **Azure OpenAI (API key)** | `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY` | `AZURE_OPENAI_API_VERSION`, `OPENAI_MODEL` |
| **Azure OpenAI (Entra ID)** | `AZURE_OPENAI_ENDPOINT` + `az login` | `AZURE_OPENAI_API_VERSION`, `OPENAI_MODEL` |
| **Custom endpoint** | `OPENAI_API_KEY`, `OPENAI_BASE_URL` | `OPENAI_MODEL` |

The server auto-detects which backend to use:
- If `AZURE_OPENAI_ENDPOINT` is set → uses `AzureOpenAI` client (with Entra ID or API key)
- Otherwise → uses `OpenAI` client (reads `OPENAI_API_KEY` and `OPENAI_BASE_URL` automatically)

The server logs which backend it detects on startup.

### Example: Azure OpenAI (API key)
```json
{
  "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]`

```json
{
  "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:

1. **Start with the spec** — paste EBNF rules from a language specification
2. **Write a basic grammar** — translate a few rules to Lark format
3. **Validate** — use `validate_grammar` to check for missing rules
4. **Write tests** — create a JSON test file with sample inputs
5. **Batch test** — use `run_batch_validation_tests` to find failures
6. **Fix & 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](examples/graphql/)** — executable subset of the GraphQL spec (queries, mutations, fragments, variables)

## Development

```bash
git clone https://github.com/guidance-ai/guidance-lark-mcp
cd guidance-lark-mcp
uv sync
uv run pytest tests/ -q
```

## Publishing

Releases are automated via GitHub Actions. To publish a new version:

```bash
git tag v0.1.0
git push origin v0.1.0
```

This triggers the release workflow which:
1. Runs tests across Python 3.10–3.12
2. Builds and publishes to PyPI (via Trusted Publishing)
3. Publishes to the MCP Registry
4. Creates a GitHub Release

PyPI publishing uses [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC) — no API tokens needed.
