STARWARCLOUD STARWAR.AI
返回市场
应用狗

应用狗

作者：rodolphebarbanneau7 星标更新：2025-09-08
安装使用来源：spider==github.com

项目介绍

AppDog

ci cov pypi versions downloads license

从任何OpenAPI规范轻松组合和生成异步API客户端和MCP服务器。

<br> <p align="center"> <img src="https://raw.githubusercontent.com/rodolphebarbanneau/appdog/refs/heads/main/docs/appdog.gif" alt="AppDog demo"> </p>

Claude桌面版目前还不支持资源模板（即带有参数的资源）。

对于Windows用户，MCP安装命令需要手动编辑生成的Claude配置。详情见此问题。

概览

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

  • 自动从OpenAPI规范生成完全类型的Python客户端
  • 创建用于API集成的现成可用的MCP（模型上下文协议）服务器
  • 在单个项目中管理多个API客户端，并锁定版本
  • 提供一个简单的CLI来添加、删除、管理和安装API客户端及MCP服务器

安装

uv add appdog

快速开始

初始化项目

# 在当前目录创建新项目
appdog init

# 或指定项目目录
appdog init --project /path/to/project

添加API客户端

# 从OpenAPI规范URL或文件添加新的API客户端
appdog add petstore --uri https://petstore3.swagger.io/api/v3/openapi.json

列出并显示可用API

# 列出项目中的所有API客户端
appdog list

# 显示特定API客户端的详细信息
appdog show petstore

升级API客户端

# 同步API客户端与项目注册表
appdog sync --upgrade

# 锁定API客户端
appdog lock --upgrade

生成MCP服务器

# 生成并安装包含所有已注册API的MCP服务器
appdog mcp install -n "我的API服务器"

# 或直接运行服务器
appdog mcp run -n "我的API服务器"

# 或在开发模式下使用检查器运行
appdog mcp dev -n "我的API服务器"

项目结构

初始化项目并添加API后，您的项目将具有以下结构：

项目/
├── apps.yaml     # 已安装API的appdog设置（自动生成）
├── apps.lock     # 包含应用规格和哈希值的锁文件（自动生成）
└── ...           # 项目文件

使用生成的客户端

添加API客户端后，您可以在代码中导入并使用它：

# 导入生成的客户端
import appdog.petstore

# 使用客户端
async def main() -> None:
    async with appdog.petstore.client as client:
        宠物 = await client.get_pet_find_by_status(status='available')
        print(宠物)

并组合自己的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:
        宠物 = await client.get_pet_find_by_status(status='available')
        return 宠物

环境变量

可以通过环境变量配置API凭证：

APPDOG_<客户端名称>_TOKEN=你的令牌
APPDOG_<客户端名称>_API_KEY=你的API密钥

MCP集成

该包包括对MCP服务器生成的全面支持：

  1. 生成MCP服务器文件：

    appdog mcp install -n "我的API服务器"

  2. 与FastMCP或其他MCP客户端一起使用：

    from appdog import Project
from mcp.server import FastMCP

mcp = FastMCP()

项目 = Project.load(project_dir=PROJECT_DIR)
项目.mount(mcp)

CLI用法

全局选项

  • --verbose, -v: 启用详细输出
  • --debug, -d: 启用所有调试日志，包括依赖项
  • --project, -p: 指定项目目录（默认为当前目录）

命令

显示CLI版本

appdog version

初始化项目

appdog init [--force] [--project PATH]
  • --force: 即使配置已经存在也强制初始化

添加API客户端

appdog add 名称 --uri URI [--base-url URL] [选项]
  • 名称: 应用程序名称
  • --uri: OpenAPI规范的URL或文件路径
  • --base-url: API调用的基础URL
  • --include-methods: 要包含的方法
  • --exclude-methods: 要排除的方法
  • --include-tags: 要包含的标签
  • --exclude-tags: 要排除的标签
  • --force: 如果已存在不同URI的应用程序，则覆盖
  • --frozen: 跳过在项目锁文件中添加应用程序规范
  • --upgrade: 强制升级应用程序规范
  • --sync: 将应用程序规范与项目注册表同步

删除API客户端

appdog remove 名称 [选项]
  • 名称: 应用程序名称
  • --frozen: 跳过从项目锁文件中移除应用程序规范
  • --sync: 将应用程序移除与项目注册表同步

列出API客户端

appdog list [--project PATH]

显示API客户端详细信息

appdog show 名称 [--project PATH]
  • 名称: 应用程序名称

锁定API规范

appdog lock [选项]
  • --force: 如果已存在不同URI的应用程序，则覆盖
  • --upgrade: 使用不同URI覆盖应用程序规范

同步API客户端

appdog sync [选项]
  • --force: 如果已存在不同URI的应用程序，则覆盖
  • --frozen: 跳过在项目锁文件中更新应用程序规范
  • --upgrade: 强制升级应用程序规范

生成MCP服务器

appdog mcp [命令] [选项]

命令：

  • install: 在MCP客户端中安装应用程序
  • run: 在生产模式下运行MCP应用程序
  • dev: 在开发模式下使用检查器运行MCP应用程序

每个命令都支持特定选项：

公共选项（所有命令）
  • --name, -n: MCP服务器名称（默认："AppDog MCP服务器"）
  • --force: 如果已存在则覆盖服务器文件
  • --project, -p: 项目目录（默认为当前目录）
  • --output, -o: MCP服务器文件的输出路径
安装命令
appdog mcp install [选项]
  • --env-var, -v: KEY=VALUE格式的环境变量
  • --env-file, -f: 包含KEY=VALUE对的环境文件
  • --with: 开发模式下要安装的附加包
  • --with-editable, -e: 开发模式下要以可编辑模式安装的本地包
运行命令
appdog mcp run [选项]
  • --transport, -t: MCP运行使用的传输方式（stdio或sse）
开发命令
appdog mcp dev [选项]
  • --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

# 自定义API密钥
客户端 = PetstoreClient(api_key="YOUR_API_KEY")

# 自定义头部
客户端 = PetstoreClient(
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)

贡献

有关如何为该项目做出贡献的信息，请参阅CONTRIBUTING.md。

许可证

本项目根据MIT许可证发布 - 详情请参阅LICENSE文件。