接通mcp
     
A. 模型上下文协议（MCP） 服务器 TOC在线 葡萄牙会计平台API。展示74种类型的工具，涵盖整个TOC Online API表面-客户、供应商、目录、销售、采购和辅助数据-因此任何兼容MCP的人工智能助手都可以直接管理您的会计。
特性
- 74个MCP工具 跨越11个领域模块
- 使用PKCE保护OAuth2 --基于浏览器的登录，令牌存储在系统密钥链中
- 自动令牌刷新 --自动将旋转刷新令牌持久化到密钥链
- 只读模式 --使用单个env var阻止所有写入操作
- 选择性模块加载 --仅加载所需的工具组
- 完全打字 --Pydantic模型驱动每个工具的模式生成
- 异步 --通过非阻塞HTTP
httpx
需求
- Python 3.12+
uv（推荐）- 具有API证书的TOC在线帐户
安装
# Clone and install dependencies
git clone https://github.com/joaovitoriasilva/toconline-mcp.git
cd toconline-mcp
uv sync认证
1.获取您的API证书
在TOC Online中，请访问 企业 > 设置 > API 数据 并注意你的：
- 客户端ID (
TOCONLINE_CLIENT_ID) - 客户端密钥 (
TOCONLINE_CLIENT_SECRET) - OAuth URL (
TOCONLINE_OAUTH_TOKEN_URL) - API URL (
TOCONLINE_BASE_URL)
2.配置环境
cp .env.example .env
# Edit .env and fill in TOCONLINE_CLIENT_ID and TOCONLINE_CLIENT_SECRET3.身份验证（一次性）
uv run toconline-mcp auth这将打开您的浏览器进行TOC在线登录。授权后，您将被重定向到回调URL——将完整的URL（或仅是代码）粘贴回终端。CLI使用PKCE将其交换为令牌（S256），并将刷新令牌安全地存储在您的 系统钥匙链 （macOS钥匙串/GNOME钥匙圈/Windows凭据管理器）。
在此之后，MCP服务器会自动更新令牌，不需要进一步的手动步骤。
检查身份验证状态
uv run toconline-mcp auth --status打印存储的刷新令牌
可用于将令牌复制到 .env Docker或CI的文件：
uv run toconline-mcp auth --show-token或者直接将其导入您的 .env:
echo "TOCONLINE_REFRESH_TOKEN=$(uv run toconline-mcp auth --show-token)" >> .env注销（删除存储的凭据）
uv run toconline-mcp auth --logout替代身份验证方法
对于系统密钥链不可用的环境（CI、Docker、无头服务器）：
| 方法 | 如何 | 安全 |
|---|---|---|
| 钥匙串 （默认） | uv run toconline-mcp auth | 由操作系统加密 |
| 静态令牌 | 设置 TOCONLINE_ACCESS_TOKEN 在 .env | 磁盘上的纯文本 |
| .env中的刷新令牌 | 设置 TOCONLINE_REFRESH_TOKEN 在 .env | 磁盘上的纯文本 |
启动时的令牌解析优先级：
TOCONLINE_ACCESS_TOKEN（env）--static，用于快速测试- 系统密钥链——安全默认
TOCONLINE_REFRESH_TOKEN（env）--CI/Docker回退
配置
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
TOCONLINE_CLIENT_ID | 是的 | "" | OAuth2客户端ID |
TOCONLINE_CLIENT_SECRET | 是的 | "" | OAuth2客户端机密 |
TOCONLINE_BASE_URL | 没有 | https://api10.toconline.pt | TOC在线API基础URL |
TOCONLINE_OAUTH_TOKEN_URL | 没有 | https://app10.toconline.pt/oauth/token | OAuth2令牌终结点 |
TOCONLINE_ACCESS_TOKEN | 没有 | "" | 静态承载令牌（跳过OAuth） |
TOCONLINE_REFRESH_TOKEN | 没有 | "" | 刷新无头envs的令牌回退 |
TOCONLINE_REDIRECT_URI | 没有 | https://oauth.pstmn.io/v1/callback | OAuth 2重定向类型 |
TOCONLINE_READ_ONLY | 没有 | false | 在以下情况下阻止所有写入操作 true |
TOCONLINE_MAX_WRITE_CALLS_PER_SESSION | 没有 | 50 | 每个MCP会话的最大写入工具调用数（0=无限制） |
TOCONLINE_MODULES | 没有 | _（全部）_ | 以逗号分隔的要加载的模块列表 |
用法
在本地运行（stdio）
uv run toconline-mcp与MCP检查员一起检查
uv run mcp dev src/toconline_mcp/server.py安装到Claude桌面
uv run mcp install src/toconline_mcp/server.py然后将环境变量添加到Claude Desktop MCP服务器配置中。
码头工人
服务器可以在容器内运行，用于无头部署或服务器部署。由于Docker没有系统密钥链，身份验证使用 TOCONLINE_REFRESH_TOKEN env变量回退。
先决条件
- 验证 一旦本地 获取刷新令牌：
uv run toconline-mcp auth- 将令牌复制到您的
.env文件：
echo "TOCONLINE_REFRESH_TOKEN=$(uv run toconline-mcp auth --show-token)" >> .env或者手动设置：
# .env
TOCONLINE_CLIENT_ID=your_client_id
TOCONLINE_CLIENT_SECRET=your_client_secret
TOCONLINE_REFRESH_TOKEN=your_refresh_token使用Docker Compose运行
# Full access (all modules, writes enabled)
docker compose up
# Read-only mode (limited modules, all writes blocked)
docker compose --profile readonly up手动构建和运行
docker build -t toconline-mcp:latest .
docker run -i --env-file .env toconline-mcp:latest工具模块
| 模块 | 工具 | 说明 |
|---|---|---|
customers | 5 | 列出、获取、创建、更新、删除客户 |
suppliers | 5 | 列出、获取、创建、更新、删除供应商 |
addresses | 5 | 管理任何实体的邮政地址 |
contacts | 5 | 管理任何实体的联系记录 |
products | 4 | 列出、创建、更新、删除产品 |
services | 4 | 列出、创建、更新、删除服务 |
sales_documents | 11 | 发票、报价、定稿、PDF、电子邮件、AT通信 |
sales_receipts | 8 | 收据、行、电子邮件 |
purchase_documents | 9 | 采购发票、行、PDF |
purchase_payments | 8 | 采购付款和额度 |
auxiliary | 10 | 税款、国家、货币、单位、银行/现金账户、费用类别、文件系列 |
选择性模块加载
要仅加载模块的子集，请设置 TOCONLINE_MODULES:
TOCONLINE_MODULES=auxiliary,customers,sales_documents uv run toconline-mcp只读模式
为防止任何数据修改：
TOCONLINE_READ_ONLY=true uv run toconline-mcp项目结构
toconline-mcp/
├── .env.example # Environment variable template
├── .python-version # Pinned Python version
├── .pre-commit-config.yaml # Pre-commit hooks (lint, format, secret detection)
├── docker-compose.yml # Docker Compose for containerised deployments
├── Dockerfile # Container image definition
├── pyproject.toml
├── README.md
├── swagger.yaml # TOC Online OpenAPI spec
├── uv.lock # Reproducible dependency lockfile
├── .github/
│ └── workflows/
│ ├── ci.yml # Lint + test on every push/PR
│ ├── security.yml # Dependency audit + secret scan
│ └── release.yml # Publish to PyPI on version tag
├── src/
│ └── toconline_mcp/
│ ├── cli.py # CLI entry point (auth, --status, --logout)
│ ├── server.py # FastMCP entry point & module loader
│ ├── app.py # FastMCP app instance & lifespan
│ ├── auth.py # OAuth2 PKCE token management
│ ├── keychain.py # Secure token storage via OS keychain
│ ├── client.py # Async httpx wrapper
│ ├── settings.py # Pydantic-settings configuration
│ └── tools/
│ ├── _base.py
│ ├── customers.py
│ ├── suppliers.py
│ ├── addresses.py
│ ├── contacts.py
│ ├── products.py
│ ├── services.py
│ ├── sales_documents.py
│ ├── sales_receipts.py
│ ├── purchase_documents.py
│ ├── purchase_payments.py
│ └── auxiliary.py
└── tests/
├── conftest.py
├── test_app.py
├── test_auth.py
├── test_base.py
├── test_client.py
├── test_keychain.py
└── test_settings.py许可证
麻省理工学院——见 许可证 了解详情。