Content
# CCH Axcess MCP Server Demo
This repository hosts a minimal [FastMCP](https://github.com/modelcontextprotocol/fastmcp) server that exposes a few helper tools for working with the CCH Axcess API. The MCP server is exported from `main.py` and can be run locally or registered with Claude Desktop.
The instructions below assume you are on Windows and want a repeatable process for setting up a fresh machine.
## Prerequisites
- Git
- [uv](https://docs.astral.sh/uv/) package manager
Install via PowerShell:
```powershell
irm https://astral.sh/uv/install.ps1 | iex
```
After installation, ensure `%USERPROFILE%\.local\bin` is on your `PATH`, or run
```powershell
%USERPROFILE%\.local\bin\env\Scripts\Activate.ps1
```
before invoking `uv`.
- Python 3.12 (uv will download the matching interpreter automatically if it is not present)
## Project Layout
```
.
├── 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
```
## One-Time Setup (per machine)
1. **Clone the repository**
```powershell
git clone https://github.com/<your-org>/mcp-server-demo.git
cd mcp-server-demo
```
2. **Create the virtual environment and install dependencies**
```powershell
uv sync --frozen
```
This creates `.venv\` in the project root with the exact package versions recorded in `uv.lock`.
3. **(Optional) Verify the install**
```powershell
.\scripts\check.ps1
```
## Running the MCP server manually
```powershell
.\scripts\devserver.ps1
```
This script will:
- Ensure dependencies are synced
- Launch `uv run mcp run main.py:mcp --transport stdio`
- Keep the process attached to your terminal until you stop it with `Ctrl+C`
Logs are written to the `logs/` directory while the server is running.
## Registering with Claude Desktop
1. Confirm the dependencies are installed (`uv sync --frozen`) and that you can run the server manually.
2. Open `C:\Users\<YOU>\AppData\Roaming\Claude\claude_desktop_config.json` and add an entry similar to:
```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"
}
}
}
```
Notes:
- `--with-editable <path>` ensures Claude uses the checked-out project rather than an empty environment.
- The final argument must be the full path to `main.py:mcp`; forward slashes avoid issues with the drive letter colon.
- Set `cwd` so relative paths inside the server resolve correctly.
3. Restart Claude Desktop. You should see **CCH Axcess** listed under the Developer Settings MCP Servers panel.
4. If the server disconnects, check `logs/mcp-server-CCH Axcess.log` for errors (missing dependencies, credential issues, etc.).
## Environment Variables
The server expects CCH credentials either from a call to the `set_cch_credentials` tool or from the environment:
| Variable | Purpose |
| --------------------- | --------------------------------------- |
| `CCH_CLIENT_ID` | OAuth client ID |
| `CCH_CLIENT_SECRET` | OAuth client secret |
| `CCH_INTEGRATOR_KEY` | Integrator key assigned by CCH |
| `CCH_REFRESH_TOKEN` | Refresh token obtained from the API |
When testing locally you can set these in PowerShell:
```powershell
$env:CCH_CLIENT_ID = "<id>"
$env:CCH_CLIENT_SECRET = "<secret>"
$env:CCH_INTEGRATOR_KEY = "<integrator>"
$env:CCH_REFRESH_TOKEN = "<token>"
```
## Working Across Windows and WSL
Avoid mixing environments (e.g., building the virtualenv from WSL and running it from Windows). If you accidentally created `.venv` under WSL, delete it from the same environment before reinstalling on Windows:
```bash
rm -rf "/mnt/c/Users/<YOU>/Documents/SAProject/Internal SSA/mcp-server-demo/.venv"
```
After cleanup, rerun `uv sync --frozen` from the Windows terminal you plan to use.
## Troubleshooting
- **ModuleNotFoundError (e.g., `requests`)**
Run `uv sync --frozen` to ensure dependencies are installed. Claude uses its own process; make sure the command in `claude_desktop_config.json` includes `--with-editable <project-path>`.
- **Editable install failure: “Multiple top-level modules discovered”**
The project declares the modules explicitly in `pyproject.toml`; pull the latest changes or ensure `[tool.setuptools].py-modules` lists `["main", "cch_api", "CCH_API_CLIENT_SNIPPET"]`.
- **File not found: `...AnthropicClaude...main`**
Update the Claude config so the final argument is the absolute path to `main.py:mcp`.
- **Server still disconnects**
Inspect `logs/mcp-server-CCH Axcess.log` for stack traces. The log often points directly to the missing dependency or configuration value.
## Development Tips
- Use the PowerShell scripts in `scripts/` for Windows; the `.sh` variants are provided for WSL or Git Bash users.
- Keep credentials out of version control. Use the `set_cch_credentials` MCP tool or environment variables during local sessions.
- When you modify dependencies, run `uv lock --upgrade` to refresh `uv.lock` and commit both `pyproject.toml` and `uv.lock`.
