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//mcp-server-demo.git
   cd mcp-server-demo

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

    uv sync --frozen

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

1. （可选）验证安装

   .\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)您可以手动运行服务器。

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

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

笔记：

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

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

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

环境变量

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

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

$env:CCH_CLIENT_ID = ""
$env:CCH_CLIENT_SECRET = ""
$env:CCH_INTEGRATOR_KEY = ""
$env:CCH_REFRESH_TOKEN = ""

跨Windows和WSL工作

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

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

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

故障排除

• ModuleNotFoundError（例如。， requests)\

跑 uv sync --frozen 以确保安装了依赖项。克劳德使用自己的过程；确保命令在 claude_desktop_config.json 包含 --with-editable .

• 可编辑安装失败：“发现多个顶级模块”\

该项目在中明确声明了模块 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.