guidance-lark-mcp

MCP Grammar Tools

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

これにより、文法の検証と一括テストをすぐに利用できます。LLM を利用した生成（generate_with_grammar）も有効にするには、ENABLE_GENERATION と認証情報を env に追加します。

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

（az login 経由の Entra ID を使用する）Azure OpenAI の場合は、代わりに guidance-lark-mcp[azure] を使用し、エンドポイントを設定します。

"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 などのエンドポイントについては、バックエンドの設定をご覧ください。

バックエンドの設定

generate_with_grammar ツールは OpenAI Python SDK を使用します。この SDK は環境変数を介して複数のバックエンドをネイティブにサポートしています。

バックエンド	必須の環境変数	任意の環境変数
OpenAI（デフォルト）	OPENAI_API_KEY	OPENAI_MODEL
Azure OpenAI（API キー）	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
カスタムエンドポイント	OPENAI_API_KEY、OPENAI_BASE_URL	OPENAI_MODEL

サーバーは使用するバックエンドを自動検出します。

• AZURE_OPENAI_ENDPOINT が設定されている場合 → AzureOpenAI クライアントを使用します（Entra ID または API キー）
• それ以外の場合 → OpenAI クライアントを使用します（OPENAI_API_KEY と OPENAI_BASE_URL を自動的に読み取ります）

サーバーは起動時に検出したバックエンドをログに記録します。

例：Azure OpenAI（API キー）

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

よくある問題：

• 認証情報がありません — 有効な OPENAI_API_KEY または AZURE_OPENAI_ENDPOINT が設定されていない状態で ENABLE_GENERATION=true にしています。サーバーは起動して検証ツールを提供しますが、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