AppDog

AppDog

あらゆる OpenAPI 仕様から、非同期 API クライアントと MCP サーバーを簡単に構成・生成できます。

Claude Desktop は、まだリソーステンプレート（つまり、パラメーターを持つリソース）に対応していません。

Windows ユーザーの場合、MCP Install コマンドの実行後に、生成された Claude 設定を手動で編集する必要があります。詳細については、この issueを参照してください。

概要

AppDog は、次の機能により、OpenAPI ベースの API を簡単に利用できる Python パッケージです。

• OpenAPI 仕様から、型付けされた Python クライアントを自動生成します
• API 連携にすぐに使える MCP（Model Context Protocol）サーバーを作成します
• バージョンを固定して、1 つのプロジェクトで複数の API クライアントを管理します
• API クライアントの追加、削除、管理や、MCP サーバーのインストールを行うシンプルな CLI を提供します

インストール

uv add appdog

クイックスタート

プロジェクトを初期化する

# Create a new project in the current directory
appdog init

# Or specify a project directory
appdog init --project /path/to/project

API クライアントを追加する

# Add a new API client from an OpenAPI spec URL or file
appdog add petstore --uri https://petstore3.swagger.io/api/v3/openapi.json

利用可能な API を一覧表示・確認する

# List all API clients in the project
appdog list

# Show details for a specific API client
appdog show petstore

API クライアントをアップグレードする

# Sync API clients with the project registry
appdog sync --upgrade

# Lock API clients
appdog lock --upgrade

MCP サーバーを生成する

# Generate and install an MCP server with all registered APIs
appdog mcp install -n "My API Server"

# Or run the server directly
appdog mcp run -n "My API Server"

# Or run in development mode with inspector
appdog mcp dev -n "My API Server"

プロジェクト構成

プロジェクトを初期化して API を追加すると、プロジェクトは次のような構成になります。

project/
├── apps.yaml     # Installed API appdog settings (auto-generated)
├── apps.lock     # Lock file with app specs and hashes (auto-generated)
└── ...           # Project files

生成したクライアントの使用

API クライアントを追加した後、コードでインポートして使用できます。

# Import generated client
import appdog.petstore

# Use the client
async def main() -> None:
    async with appdog.petstore.client as client:
        pets = await client.get_pet_find_by_status(status='available')
        print(pets)

独自の MCP サーバーを構成することもできます。

import appdog.petstore
from mcp.server import FastMCP

mcp = FastMCP()

@mcp.tool()
async def hello_petstore() -> str:
    async with appdog.petstore.client as client:
        pets = await client.get_pet_find_by_status(status='available')
        return pets

環境変数

API 認証情報は環境変数を使って設定できます。

APPDOG_<CLIENT_NAME>_TOKEN=your_token
APPDOG_<CLIENT_NAME>_API_KEY=your_api_key

MCP 連携

このパッケージは、MCP サーバーの生成を全面的にサポートしています。

1. MCP サーバーファイルを生成します。

   appdog mcp install -n "My API Server"
   

2. FastMCP またはその他の MCP クライアントで使用します。

   from appdog import Project
   from mcp.server import FastMCP
   
   mcp = FastMCP()
   
   project = Project.load(project_dir=PROJECT_DIR)
   project.mount(mcp)
   

CLI の使用方法

グローバルオプション

• --verbose, -v: 詳細な出力を有効にします
• --debug, -d: 依存関係を含むすべてのデバッグログを有効にします
• --project, -p: プロジェクトディレクトリを指定します（デフォルトはカレントディレクトリです）

コマンド

CLI のバージョンを表示する

appdog version

プロジェクトを初期化する

appdog init [--force] [--project PATH]

• --force: 設定がすでに存在する場合でも、強制的に初期化します

API クライアントを追加する

appdog add NAME --uri URI [--base-url URL] [OPTIONS]

• NAME: アプリケーション名
• --uri: OpenAPI 仕様の URL またはファイルパス
• --base-url: API 呼び出しに使用するベース URL
• --include-methods: 含めるメソッド
• --exclude-methods: 除外するメソッド
• --include-tags: 含めるタグ
• --exclude-tags: 除外するタグ
• --force: URI が異なるアプリケーションがすでに存在する場合、そのアプリケーションを上書きします
• --frozen: プロジェクトのロックファイルへのアプリケーション仕様の追加をスキップします
• --upgrade: アプリケーション仕様を強制的にアップグレードします
• --sync: アプリケーション仕様をプロジェクトレジストリと同期します

API クライアントを削除する

appdog remove NAME [OPTIONS]

• NAME: アプリケーション名
• --frozen: プロジェクトのロックファイルからのアプリケーション仕様の削除をスキップします
• --sync: アプリケーションの削除をプロジェクトレジストリと同期します

API クライアントを一覧表示する

appdog list [--project PATH]

API クライアントの詳細を表示

appdog show NAME [--project PATH]

• NAME：アプリケーション名

API 仕様をロック

appdog lock [OPTIONS]

• --force：異なる URI を持つアプリケーションが存在する場合、上書きします
• --upgrade：異なる URI を持つアプリケーション仕様で上書きします

API クライアントを同期

appdog sync [OPTIONS]

• --force：異なる URI を持つアプリケーションが存在する場合、上書きします
• --frozen：プロジェクトのロックファイル内のアプリケーション仕様の更新をスキップします
• --upgrade：アプリケーション仕様を強制的にアップグレードします

MCP サーバーを生成

appdog mcp [COMMAND] [OPTIONS]

コマンド：

• install：MCP クライアントにアプリケーションをインストールします
• run：本番モードで MCP アプリケーションを実行します
• dev：インスペクター付きの開発モードで MCP アプリケーションを実行します

各コマンドは固有のオプションをサポートします。

共通オプション（すべてのコマンド）

• --name、-n：MCP サーバー名（デフォルト："AppDog MCP Server"）
• --force：サーバーファイルが存在する場合、上書きします
• --project、-p：プロジェクトディレクトリ（デフォルトは現在のディレクトリ）
• --output、-o：MCP サーバーファイルの出力先パス

Install コマンド

appdog mcp install [OPTIONS]

• --env-var、-v：KEY=VALUE 形式の環境変数
• --env-file、-f：KEY=VALUE のペアを含む環境ファイル
• --with：開発モードでインストールする追加パッケージ
• --with-editable、-e：編集可能モードでインストールするローカルパッケージ

Run コマンド

appdog mcp run [OPTIONS]

• --transport、-t：MCP の実行に使用するトランスポート（stdio または sse）

Dev コマンド

appdog mcp dev [OPTIONS]

• --with：開発モードでインストールする追加パッケージ
• --with-editable、-e：編集可能モードでインストールするローカルパッケージ

高度な使い方

クライアント設定

API クライアントを設定するため、カスタムの apps.yaml を作成します。

petstore:
  uri: https://petstore3.swagger.io/api/v3/openapi.json
  base_url: https://petstore3.swagger.io/api/v3
  include_tags:
    - pet
    - store

カスタム認証

MCP の使用方法については、環境変数のセクションを参照してください

カスタム認証を使用するクライアントを作成します。

from appdog.petstore import PetstoreClient

# Custom API key
client = PetstoreClient(api_key="YOUR_API_KEY")

# Custom headers
client = PetstoreClient(
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)

貢献

プロジェクトへの貢献については、CONTRIBUTING.mdを参照してください。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSEファイルを参照してください。