tcxc-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP server implementation for TelecomsXChange (TCXC) API integration, providing Claude and LLMs with access to wholesale telecommunications APIs for voice termination, SMS, DIDs, and account management.

Development Commands

# Setup
pip install -r requirements.txt          # Install dependencies
pip install -e ".[dev]"                   # Install with dev tools (pytest, black, mypy)
cp .env.example .env                      # Create config from template

# Run server
./start_mcp_server.sh                     # Production (uses venv)
python src/tcxc_mcp/server.py             # Direct execution

# Interactive testing
python src/tcxc_mcp/mcp_client.py         # Test tools interactively

# Code quality
make format                               # black + isort
make lint                                 # black --check + isort --check + mypy
make typecheck                            # mypy only
make test                                 # pytest with coverage

# Run single test
pytest tests/test_validation.py -v
pytest tests/test_validation.py::test_function_name -v

Architecture

src/tcxc_mcp/
├── server.py      # FastMCP server entry point, creates TCXCMCPServer
├── client.py      # HTTPX async client with digest auth, rate limiting, TLS hardening
├── config.py      # Pydantic settings, loads from .env with TCXC_ prefix
├── tools.py       # MCP tool implementations (46+ tools), input validation
└── prompts.py     # Guided workflows for complex tasks (7 prompts)

Request Flow: FastMCP → tool function → TCXCClient → TCXC API

Key Design Patterns:

• Async context managers for client lifecycle (async with TCXCClient(config) as client)
• Rate limiting via semaphore + time-based throttling in client.py
• Input validation with security checks before API calls (validate_phone_number, validate_search_prefix, validate_date_format)
• Endpoint whitelisting in _make_request prevents path traversal