guidance-lark-mcp

MCP 语法工具

用于验证和测试 llguidance 语法（Lark 格式）的 MCP 服务。提供语法验证、批量测试执行和语法文档，非常适合与 AI 编码助手协作，迭代构建语法。

安装

使用 uvx（推荐）

uvx guidance-lark-mcp

使用 pip

pip install guidance-lark-mcp

从源代码安装

cd mcp-grammar-tools
pip install -e .

MCP 客户端配置

GitHub Copilot CLI

你可以使用交互式 /mcp add 命令添加服务，也可以直接编辑配置文件。完整详情请参阅 Copilot CLI MCP 文档。

选项 1：交互式设置

在 Copilot CLI 中运行 /mcp add，选择 Local/STDIO，并输入 uvx guidance-lark-mcp 作为命令。

选项 2：编辑配置文件

将以下内容添加到 ~/.copilot/mcp-config.json：

{
  "mcpServers": {
    "grammar-tools": {
      "type": "local",
      "command": "uvx",
      "args": ["guidance-lark-mcp"],
      "tools": ["*"]
    }
  }
}

这样即可直接使用语法验证和批量测试。若还要启用由大模型驱动的生成（generate_with_grammar），请将 ENABLE_GENERATION 和你的凭据添加到 env：

"env": {
  "ENABLE_GENERATION": "true",
  "OPENAI_API_KEY": "your-key-here"
}

对于 Azure OpenAI（通过 az login 使用 Entra ID），请使用 guidance-lark-mcp[azure]，并改为设置 endpoint：

"args": ["guidance-lark-mcp[azure]"],
"env": {
  "ENABLE_GENERATION": "true",
  "AZURE_OPENAI_ENDPOINT": "https://your-resource.openai.azure.com/",
  "OPENAI_MODEL": "your-deployment-name"
}

所有受支持的后端请参阅后端配置。

保存后，使用 /mcp show 确认服务已连接。

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"
      }
    }
  }
}

用法

可用工具

1. validate_grammar — 使用 llguidance 内置的验证器检查语法的完整性和一致性。

   {"grammar": "start: \"hello\" \"world\""}
   

2. run_batch_validation_tests — 根据某个语法，运行 JSON 文件中的批量验证测试。返回通过/失败统计信息和详细的失败信息。

   {
     "grammar": "start: /[0-9]+/",
     "test_file": "tests.json"
   }
   

   测试文件格式：

   [
     {"input": "123", "should_parse": true, "description": "Valid number"},
     {"input": "abc", "should_parse": false, "description": "Not a number"}
   ]
   

3. get_llguidance_documentation — 从官方仓库获取 llguidance 语法文档。

4. generate_with_grammar （可选，需要 ENABLE_GENERATION=true） — 使用受语法约束的 OpenAI 模型生成文本。采用 Responses API 的自定义工具语法格式，因此输出保证符合语法要求。需要设置 OPENAI_API_KEY 环境变量。Azure 和其他 endpoint 的配置请参阅后端配置。

后端配置

generate_with_grammar 工具使用 OpenAI Python SDK，该 SDK 可通过环境变量原生支持多个后端：

后端	必需的环境变量	可选的环境变量
OpenAI（默认）	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
自定义 endpoint	OPENAI_API_KEY、OPENAI_BASE_URL	OPENAI_MODEL

服务会自动检测要使用的后端：

• 如果设置了 AZURE_OPENAI_ENDPOINT → 使用 AzureOpenAI 客户端（通过 Entra ID 或 API key）
• 否则 → 使用 OpenAI 客户端（自动读取 OPENAI_API_KEY 和 OPENAI_BASE_URL）

服务启动时会记录检测到的后端。

示例：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": ["*"]
    }
  }
}

示例：Azure OpenAI（Entra ID / 无密钥）

需要运行 az login，并安装 azure 附加组件：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": ["*"]
    }
  }
}

示例工作流

与 AI 助手协作，迭代构建语法：

1. 从规范开始 — 粘贴语言规范中的 EBNF 规则
2. 编写基本语法 — 将几条规则转换为 Lark 格式
3. 验证 — 使用 validate_grammar 检查是否有缺失的规则
4. 编写测试 — 创建包含示例输入的 JSON 测试文件
5. 批量测试 — 使用 run_batch_validation_tests 查找失败项
6. 修复并重复 — 不断完善语法，直到所有测试通过

示例语法

examples/ 目录包含使用这些工具构建的示例语法，其中包括 Lark 语法文件、测试套件和文档：

• GraphQL — GraphQL 规范的可执行子集（查询、变更、片段、变量）

故障排除

Copilot CLI / VS Code 中的服务无法连接？

Copilot CLI 等 MCP 客户端只会在服务启动时崩溃的情况下显示“Connection closed”。要查看实际错误，请在终端中直接运行服务：

uvx guidance-lark-mcp

或者启用生成：

ENABLE_GENERATION=true OPENAI_API_KEY=your-key uvx guidance-lark-mcp

常见问题：

• 缺少凭据 — 设置了 ENABLE_GENERATION=true，但没有有效的 OPENAI_API_KEY 或 AZURE_OPENAI_ENDPOINT。服务仍会启动并提供验证工具；generate_with_grammar 会返回一条说明性错误。
• Azure Entra ID — 确保已运行 az login，并使用 guidance-lark-mcp[azure]（而不是基础包）。
• 首次启动较慢 — uvx 首次运行时需要解析并安装依赖项，耗时可能超过 MCP 客户端的连接超时时间。手动运行一次 uvx guidance-lark-mcp 以预热缓存。
• 更新到新版本 — uvx 会缓存软件包，因此发布新版本后，你可能需要清除缓存并重启 MCP 客户端：

  uv cache clean guidance-lark-mcp
  

开发

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