内容
# Allegro MCP
[](https://github.com/piotrlinski/allegro-open-mcp-server/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://mypy-lang.org/)
一款适用于Allegro REST API的Python MCP服务器，由可分离的`allegro_client` SDK支持。
```text
src/
├── allegro_client/ # 与MCP无关 — 可作为独立的PyPI包提取
└── allegro_mcp/ # FastMCP包装器，暴露268种工具
```
## 亮点
* **268种MCP工具**，涵盖Allegro所有约30个资源组（报价、订单、发货、消息、计费、退货、纠纷、支付、促销、履约等）。
* **四种OAuth流**：设备代码（推荐用于MCP）、带有PKCE的授权代码、客户端凭证和预共享刷新令牌。
* **持久令牌存储**，位于`~/.allegro-mcp/tokens.json`（模式`0600`，原子写入，刷新令牌轮换自动处理）。
* **沙盒 + 生产**环境，只需一个环境变量切换。
* **写入门控** — 高风险变异工具在`ALLEGRO_ENABLE_WRITES=true`之前拒绝触发。默认情况下，大多数读取操作是安全的。
* **生成的Pydantic模型**，从Allegro的官方OpenAPI 3.0规范通过[datamodel-code-generator](https://github.com/koxudaxi/datamodel-code-generator)代码生成。
* **生产级工具**：mypy `--strict`、ruff、预提交钩子、多阶段Docker构建、Python 3.10/3.11/3.12上的GitHub Actions CI。
* **250+单元测试**，包括一个保护未来包提取边界的层强制测试。
* **MIT许可**，不隶属于Allegro集团。第三方运行时依赖许可在[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)中记录。
## 快速入门
最快捷的方式是使用`uvx` — 无需克隆，无需虚拟环境，无需安装：
```bash
ALLEGRO_CLIENT_ID=你的客户端ID \
ALLEGRO_CLIENT_SECRET=你的客户端密钥 \
ALLEGRO_AUTH_FLOW=device \
uvx --from git+https://github.com/piotrlinski/allegro-open-mcp-server allegro-mcp
```
`uvx`解析包，安装到临时虚拟环境中，并运行`allegro-mcp`控制台脚本。第一次运行`ALLEGRO_AUTH_FLOW=device`会在标准错误中打印验证URL + 用户代码；在浏览器中批准后，刷新令牌将持续保存在`~/.allegro-mcp/tokens.json`中，以便下次使用。
要固定版本（或测试分支/PR），请追加`@<修订版本>`：
```bash
uvx --from git+https://github.com/piotrlinski/allegro-open-mcp-server@v0.1.0 allegro-mcp
```
CLI标志与环境变量的作用相同 — 在连接MCP客户端时非常方便：
```bash
uvx --from git+https://github.com/piotrlinski/allegro-open-mcp-server allegro-mcp \
--client-id 你的客户端ID \
--client-secret 你的客户端密钥 \
--auth-flow device \
--environment sandbox
```
如果您更喜欢从克隆开始：
```bash
git clone https://github.com/piotrlinski/allegro-open-mcp-server
cd allegro-open-mcp-server
uv sync --extra dev
cp .env.example .env # 填写 ALLEGRO_CLIENT_ID、ALLEGRO_CLIENT_SECRET、ALLEGRO_AUTH_FLOW
uv run allegro-mcp # 通过stdio与MCP通信
```
完整的操作指南 → [docs/tutorials/quickstart.md](docs/tutorials/quickstart.md)。
## 身份验证
| 流 | 使用场景 |
| --- | --- |
| `device`（推荐） | 无头MCP服务器；第一次运行会将URL+代码打印到标准错误中 |
| `authcode` | 操作员在同一主机上；启动本地主机回调监听器 |
| `client_credentials` | 仅限应用访问公共资源 |
| `refresh_token` | 预共享刷新令牌，无需交互式身份验证 |
在[docs/how-to/oauth-flows.md](docs/how-to/oauth-flows.md)中选择一个。
## MCP客户端设置
* **Claude Desktop** — [docs/how-to/with-claude-desktop.md](docs/how-to/with-claude-desktop.md)
* **Claude Code** — [docs/how-to/with-claude-code.md](docs/how-to/with-claude-code.md)
* **MCP Inspector** — `make inspector`
## 开发
```bash
make sync # 安装开发依赖
make test # 运行pytest（250+测试）
make lint # ruff + mypy --strict
make format # 应用ruff格式化 + 自动修复
make gen-models # 从OpenAPI规范重新生成Pydantic模型
make gen-tools # 从规范重新生成MCP工具模块
make check-models-freshness # 如果上游规范移动，发出警告
make build # 构建Docker镜像
make run # 在Docker中运行服务器（stdio）
make inspector # 在Docker镜像上运行MCP Inspector
make docs-serve # 在http://127.0.0.1:8000上实时加载文档
```
## 架构
两个包，目前是一个轮子，将来会有两个独立的PyPI发行版：
```text
allegro_client.config → allegro_client.errors → allegro_client.auth →
allegro_client.http → allegro_client.models # 与MCP无关的SDK
allegro_mcp.config → allegro_mcp.errors → allegro_mcp.logging →
allegro_mcp.tools → allegro_mcp.server # FastMCP包装器
```
边界由`tests/unit/test_architecture.py`强制执行 — 如果`allegro_client`曾经导入`fastmcp`、`mcp`或`allegro_mcp.*`，CI就会失败。
阅读更多：[docs/explanation/architecture.md](docs/explanation/architecture.md)
## 贡献
欢迎提交PR。请参阅[CONTRIBUTING.md](CONTRIBUTING.md)。
## 安全
发现漏洞？请遵循[SECURITY.md](SECURITY.md)。
## 许可证
[MIT](LICENSE) — 社区项目；不隶属于Allegro集团。
