AI导哈

CCH Axcess API工具服务器

一个基于FastMCP的服务器，提供CCH Axcess API的辅助工具，适用于税务软件集成和开发环境设置。

  • by thuong-lino
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 thuong-lino/cch-mcp-demo

使用说明

CCH Axcess MCP服务器演示

此存储库承载了最小 FastMCP 服务器，它公开了一些用于使用CCH Axcess API的辅助工具。MCP服务器从导出 main.py 并且可以在本地运行或向Claude Desktop注册。

以下说明假设您使用的是Windows，并希望有一个可重复的过程来设置新机器。

先决条件

  • Git
  • 紫外线 包管理器
    通过PowerShell安装：
    irm https://astral.sh/uv/install.ps1 | iex
    安装后，确保 %USERPROFILE%\.local\bin 在你的 PATH，或运行
    %USERPROFILE%\.local\bin\env\Scripts\Activate.ps1
    在调用之前 uv.
  • Python 3.12（如果匹配的解释器不存在，uv会自动下载）

项目布局

.
├── main.py                    # FastMCP entry point exporting `mcp`
├── cch_api.py                 # Thin wrapper around the CCH Axcess REST API
├── CCH_API_CLIENT_SNIPPET.py  # Reference snippet from the API docs
├── scripts/                   # Helper scripts (PowerShell and bash)
├── logs/                      # Runtime logs (ignored in git)
├── pyproject.toml             # Project metadata and dependencies
└── uv.lock                    # Pinned dependency versions

一次性设置（每台机器）

  1. 克隆存储库

    git clone https://github.com/<your-org>/mcp-server-demo.git
cd mcp-server-demo

  2. 创建虚拟环境并安装依赖项

     uv sync --frozen

    这创造了 .venv\ 在项目根目录中，记录了确切的包版本 uv.lock.

  3. （可选）验证安装

    .\scripts\check.ps1

手动运行MCP服务器

.\scripts\devserver.ps1

此脚本将：

  • 确保相关性已同步
  • 发射 uv run mcp run main.py:mcp --transport stdio
  • 将进程连接到您的终端，直到您用以下命令停止它 Ctrl+C

日志被写入 logs/ 服务器运行时的目录。

在Claude Desktop注册

  1. 确认已安装依赖项(uv sync --frozen)您可以手动运行服务器。

  2. 打开 C:\Users\<YOU>\AppData\Roaming\Claude\claude_desktop_config.json 并添加类似于以下内容的条目：

    {
  "mcpServers": {
    "CCH Axcess": {
      "command": "C:\\\\Users\\\\<YOU>\\\\.local\\\\bin\\\\uv.EXE",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "C:\\\\Users\\\\<YOU>\\\\Documents\\\\SAProject\\\\Internal SSA\\\\mcp-server-demo",
        "mcp",
        "run",
        "C:/Users/<YOU>/Documents/SAProject/Internal SSA/mcp-server-demo/main.py:mcp"
      ],
      "cwd": "C:\\\\Users\\\\<YOU>\\\\Documents\\\\SAProject\\\\Internal SSA\\\\mcp-server-demo"
    }
  }
}

    笔记：

    • --with-editable <path> 确保Claude使用已签出的项目，而不是空的环境。
    • 最后一个论点必须是完整的路径 main.py:mcp；正斜杠可避免驱动器号冒号出现问题。
    • 集 cwd 因此服务器内部的相对路径可以正确解析。

  3. 重新启动克劳德桌面。你应该看看 CCH Axcess 列在“开发人员设置MCP服务器”面板下。

  4. 如果服务器断开连接，请检查 logs/mcp-server-CCH Axcess.log 错误（缺少依赖关系、凭据问题等）。

环境变量

服务器需要来自呼叫的CCH凭据 set_cch_credentials 工具或环境：

变量 目的
CCH_CLIENT_ID OAuth客户端ID
CCH_CLIENT_SECRET OAuth客户端密钥
CCH_INTEGRATOR_KEY CCH分配的集成商密钥
CCH_REFRESH_TOKEN 从API获取的刷新令牌

在本地测试时，您可以在PowerShell中设置这些：

$env:CCH_CLIENT_ID = "<id>"
$env:CCH_CLIENT_SECRET = "<secret>"
$env:CCH_INTEGRATOR_KEY = "<integrator>"
$env:CCH_REFRESH_TOKEN = "<token>"

跨Windows和WSL工作

避免混合环境（例如，从WSL构建virtualenv并从Windows运行它）。如果您意外创建 .venv 在WSL下，在Windows上重新安装之前，从同一环境中将其删除：

rm -rf "/mnt/c/Users/<YOU>/Documents/SAProject/Internal SSA/mcp-server-demo/.venv"

清理后，重新运行 uv sync --frozen 从您计划使用的Windows终端。

故障排除

  • ModuleNotFoundError（例如。， requests)
    跑 uv sync --frozen 以确保安装了依赖项。克劳德使用自己的过程；确保命令在 claude_desktop_config.json 包含 --with-editable <project-path>.

  • 可编辑安装失败：“发现多个顶级模块”
    该项目在中明确声明了模块 pyproject.toml；拉取最新更改或确保 [tool.setuptools].py-modules 列表 ["main", "cch_api", "CCH_API_CLIENT_SNIPPET"].

  • 找不到文件： ...AnthropicClaude...main
    更新Claude配置，使最后一个参数是 main.py:mcp.

  • 服务器仍然断开连接
    检查 logs/mcp-server-CCH Axcess.log 用于堆栈痕迹。日志通常直接指向缺少的依赖关系或配置值。

开发技巧

  • 在中使用PowerShell脚本 scripts/ 适用于Windows；这 .sh 为WSL或Git Bash用户提供了变体。
  • 将凭据置于版本控制之外。使用 set_cch_credentials 本地会话期间的MCP工具或环境变量。
  • 修改依赖关系时，运行 uv lock --upgrade 刷新 uv.lock 并承诺两者 pyproject.toml 和 uv.lock.

相关 MCP