AppDog

AppDog

轻松组合并生成异步 API 客户端和 MCP 服务，支持任意 OpenAPI 规范。

Claude Desktop 目前尚不支持资源模板（即带参数的资源）。

对于 Windows 用户，MCP Install 命令需要手动编辑生成的 Claude 配置。详情请参阅此问题。

概述

AppDog 是一个 Python 包，通过以下方式简化基于 OpenAPI 的 API 的使用：

• 根据 OpenAPI 规范自动生成完全类型化的 Python 客户端
• 创建可直接使用的 MCP（Model Context Protocol）服务，用于集成 API
• 在单个项目中管理多个 API 客户端，并锁定版本
• 提供简单的 CLI，用于添加、移除和管理 API 客户端，以及安装 MCP 服务

安装

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：以可编辑模式安装的本地软件包

高级用法

客户端配置

创建自定义的 apps.yaml 来配置 API 客户端：

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 文件。