Metadata-Version: 2.4
Name: point-topic-mcp
Version: 0.2.2
Summary: UK broadband data analysis MCP server with Snowflake integration
Project-URL: Homepage, https://github.com/point-topic/point-topic-mcp
Project-URL: Repository, https://github.com/point-topic/point-topic-mcp
Author-email: Peter Donaghey <peter.donaghey@point-topic.com>
License: MIT
Keywords: broadband,data-analysis,mcp,snowflake
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: boto3>=1.28.0
Requires-Dist: certifi>=2024.0.0
Requires-Dist: clickhouse-connect>=0.8.0
Requires-Dist: cryptography>=44.0.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: fastmcp>=2.14.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=1.26.0
Requires-Dist: pygithub>=2.1.1
Requires-Dist: pyjwt>=2.10.0
Requires-Dist: pymongo>=4.10.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: snowflake-connector-python>=3.17.3
Requires-Dist: uvicorn>=0.34.0
Provides-Extra: snowflake
Requires-Dist: pandas>=1.5.0; extra == 'snowflake'
Requires-Dist: pyarrow>=12.0.0; extra == 'snowflake'
Description-Content-Type: text/markdown

# Point Topic MCP Server

UK broadband data analysis server via Model Context Protocol. Queries the Point Topic ontology (ClickHouse) for all UK broadband data — footprint, speeds, take-up, forecasts, tariffs, and demographics.

## ✅ what's implemented

**database tools** (ClickHouse — requires CLICKHOUSE_HOST + CLICKHOUSE_PASSWORD):
- `execute_query()` - run safe read-only SQL against the ontology. The tool description embeds the ontology data model (key tables, aspects, ClickHouse dialect) — no context assembly needed.
- `get_onto_network_overview()` - comprehensive overview of a single network
- `get_onto_net_op_overview()` - overview of a network operator
- `get_onto_isp_overview()` - overview of an ISP
- `get_onto_schema()` - list all ontology tables with columns and descriptions
- `assemble_dataset_context()` - get supplementary schemas and examples for specific datasets

**database tools** (Snowflake — dev only, requires `ENABLE_SNOWFLAKE=true`):
- `execute_snowflake_query()` - run SQL against legacy Snowflake tables
- `get_query_status()` / `cancel_query()` - manage long-running queries
- `describe_table()` / `get_la_code()` / `get_la_list_full()` - table schema & LA lookups
- `get_dataset_status()` - check latest data availability dates

**chart tools**:
- `get_point_topic_public_chart_catalog()` - browse public charts (no auth needed)
- `get_point_topic_public_chart_csv()` - get public chart data as CSV (no auth needed)
- `get_point_topic_chart_catalog()` - get complete catalog including private charts (requires API key)
- `get_point_topic_chart_csv()` - get any chart data as CSV with authentication (requires API key)
- `generate_authenticated_chart_url()` - create signed URLs for private charts (requires API key)

**server info**:
- `get_mcp_server_capabilities()` - check which tools are available and debug missing credentials

**prompts** (reusable message templates):
- UPC analysis: analyze coverage, adoption, forecasts, and market dynamics

**conditional availability**: tools only appear if required environment variables are set

## installation (for end users)

**option 1: pip install (recommended)**:

```bash
pip install point-topic-mcp
```

if you encounter `cmake` build errors during installation (for pyarrow), install with Snowflake support explicitly:

```bash
pip install "point-topic-mcp[snowflake]"
```

or provide pre-built wheels:

```bash
pip install --only-binary :all: point-topic-mcp[snowflake]
```

**option 2: from source (with uv)**:

```bash
git clone https://github.com/point-topic/point-topic-mcp.git
cd point-topic-mcp
uv sync
uv run point-topic-mcp
```

**add to your MCP client** (Claude Desktop, Cursor, etc.):

```json
{
  "mcpServers": {
    "point-topic": {
      "command": "point-topic-mcp",
      "env": {
        "CLICKHOUSE_HOST": "db.point-topic.com",
        "CLICKHOUSE_PORT": "443",
        "CLICKHOUSE_DATABASE": "ontology",
        "CLICKHOUSE_USER": "your_user",
        "CLICKHOUSE_PASSWORD": "your_password"
      }
    }
  }
}
```

For Snowflake dev access, add:
```json
"ENABLE_SNOWFLAKE": "true",
"SNOWFLAKE_USER": "your_user",
"SNOWFLAKE_PASSWORD": "your_password"
```

## remote deployment (FastMCP Cloud)

Deploy the MCP server remotely to FastMCP Cloud for access from any MCP client.

**requirements:**
- FastMCP Cloud account (https://fastmcp.cloud)
- GitHub repository connected to FastMCP Cloud

**deployment:**

1. Sign up at https://fastmcp.cloud
2. Connect repository: `Point-Topic/point-topic-mcp`
3. Configure environment variables (ClickHouse credentials)
4. Deploy - FastMCP Cloud handles HTTPS, scaling, monitoring automatically

**client connections:**

*Claude Desktop (via mcp-remote):*
```json
{
  "mcpServers": {
    "point-topic": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-url.fastmcp.cloud/mcp"]
    }
  }
}
```

*Cursor (native remote):*
```json
{
  "mcpServers": {
    "point-topic": {
      "url": "https://your-url.fastmcp.cloud/mcp",
      "transport": "http"
    }
  }
}
```

See [docs/REMOTE_SERVER.md](docs/REMOTE_SERVER.md) for complete deployment guide.

**note**: environment variables are optional - tools will only appear if credentials are provided. use `get_mcp_server_capabilities()` to check which tools are available.

**Claude Desktop config location**:
- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

## development setup

setup: `uv sync`

**for local development with claude desktop**:

This will add the server to your claude desktop config.

```bash
uv run mcp install src/point_topic_mcp/server_local.py -f .env

For Snowflake dev access, add `--with "snowflake-connector-python[pandas]"`:

```bash
uv run mcp install src/point_topic_mcp/server_local.py --with "snowflake-connector-python[pandas]" -f .env
```
```

**for mcp inspector**:

```bash
uv run mcp dev src/point_topic_mcp/server_local.py
```

**environment configuration**:

create `.env` file with your credentials.

**Required for all users:**
```bash
# ClickHouse credentials for ontology queries (primary data path — always needed)
CLICKHOUSE_HOST=db.point-topic.com
CLICKHOUSE_PORT=443
CLICKHOUSE_DATABASE=ontology
CLICKHOUSE_USER=your_user
CLICKHOUSE_PASSWORD=your_password
```

**Optional — Snowflake dev access:**
```bash
# Enable legacy Snowflake tools (dev only — set ENABLE_SNOWFLAKE=true to show them)
ENABLE_SNOWFLAKE=true
SNOWFLAKE_USER=your_user
SNOWFLAKE_PASSWORD=your_password
```

**Optional — other tools:**
```bash
# Chart API key (for authenticated chart generation)
CHART_API_KEY=your_chart_api_key

# PT Research MongoDB (for GBS tools)
PT_RESEARCH_DATABASE_URI=mongodb+srv://...

# GitHub token (for GitHub org tools)
GITHUB_TOKEN=your_github_token
```

**GBS tools** require mongosh installed:

```bash
# After pip/uv install, run (sudo needed on Linux):
point-topic-mcp-install-mongosh
```

## architecture

**stdio transport**: communicates with MCP clients via standard input/output for local integration

**auto-discovery**: tools and datasets are automatically discovered from module files - no manual registration needed

**conditional tools**: tools only register if required environment variables are present - use `get_mcp_server_capabilities()` to debug

**modular design**:
- `src/point_topic_mcp/tools/` - tool modules auto-discovered and registered
- `src/point_topic_mcp/context/datasets/` - dataset modules auto-discovered for context assembly

## adding new tools

this project uses auto-discovery for tools - just add a function and it becomes available.

### tool structure

create a file in `src/point_topic_mcp/tools/` ending with `_tools.py`:

```python
# src/point_topic_mcp/tools/my_feature_tools.py

from typing import Optional
from mcp.server.fastmcp import Context
from mcp.server.session import ServerSession

def my_new_tool(param: str, ctx: Optional[Context[ServerSession, None]] = None) -> str:
    """Tool description visible to agents."""
    # your implementation
    return "result"
```

**that's it!** the tool is automatically discovered and registered.

### conditional tools (require credentials)

use `check_env_vars()` to conditionally define tools:

```python
from point_topic_mcp.core.utils import check_env_vars
from dotenv import load_dotenv

load_dotenv()

if check_env_vars('my_feature', ['MY_API_KEY']):
    def authenticated_tool(ctx: Optional[Context[ServerSession, None]] = None) -> str:
        """Only available if MY_API_KEY is set."""
        import os
        api_key = os.getenv('MY_API_KEY')
        # use api_key...
        return "result"
```

### key principles

1. **auto-discovery**: any public function in `*_tools.py` files becomes a tool
2. **conditional registration**: wrap in `if check_env_vars()` for authenticated tools
3. **clear docstrings**: visible to agents at all times - keep concise and actionable
4. **type hints**: use for better agent understanding

### dynamic tool registration

for registering tools at runtime (e.g., when new datasets become available), use the `ToolManager` class:

```python
from point_topic_mcp.core.tool_manager import ToolManager
from mcp.server.fastmcp import Context
import mcp.types

# Create tool manager
tool_manager = ToolManager(mcp)

# Define a new tool
async def analyze_new_dataset(dataset_id: str) -> dict:
    """Analyze data from a newly added dataset."""
    return {"status": "analyzed", "dataset": dataset_id}

# Register it
tool_manager.register_tool(
    name="analyze_dataset",
    description="Analyze newly added datasets",
    function=analyze_new_dataset
)

# Optional: notify clients of the change
@mcp.tool()
async def notify_new_tool(ctx: Context) -> str:
    """Notify clients that tools have changed."""
    await ctx.send_notification(mcp.types.ToolListChangedNotification())
    return "Clients notified"
```

when you call `tool_manager.register_tool()`, the tool is added to FastMCP. to notify connected MCP clients about the change (so they can refresh their tool lists), call `ctx.send_notification()` with `ToolListChangedNotification()` from within a tool function. see the [MCP specification](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#list-changed-notification) for more details.

## prompts

the server exposes reusable message templates and workflows via MCP prompts. prompts appear in the prompt picker in MCP clients (Cursor, Claude Desktop, etc.) and provide standardized workflows for common analysis tasks.

### available prompts

**UPC Analysis Prompts** (UK broadband coverage data):
- `upc_analysis_prompt` - analyze coverage, take-up, forecasts, or market dynamics for a local authority
- `upc_regional_comparison_prompt` - compare metrics across multiple regions
- `upc_forecasting_prompt` - generate forward-looking coverage and adoption forecasts
- `upc_market_analysis_prompt` - understand competitive dynamics and ISP strategies

The ontology data model and ClickHouse dialect are embedded in `execute_query`'s tool description — no SQL assistance prompts needed for the primary data path.

### adding new prompts

this project uses auto-discovery for prompts - just add a function and it becomes available.

#### prompt structure

create a file in `src/point_topic_mcp/prompts/` ending with `_prompts.py`:

```python
# src/point_topic_mcp/prompts/my_analysis_prompts.py

from typing import List
from mcp.types import PromptMessage, TextContent

def my_analysis_prompt(
    region: str,
    metric: str = "default"
) -> List[PromptMessage]:
    """Brief description of what this prompt helps with.
    
    Args:
        region: Description of the region parameter
        metric: Description of the metric parameter
    
    Returns:
        List of PromptMessage objects that form the prompt
    """
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text="System context or instructions here"
            )
        ),
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"User query incorporating {region} and {metric}"
            )
        ),
        # Add more messages as needed
    ]
```

**that's it!** the prompt is automatically discovered and registered.

#### key principles

1. **auto-discovery**: any public function in `*_prompts.py` files becomes a prompt
2. **clear docstrings**: visible to agents - describe what the prompt helps with
3. **message structure**: return `List[PromptMessage]` where each message has role ("user" or "assistant") and TextContent
4. **parameters**: use type hints for parameters - they become prompt arguments in the MCP client
5. **context-aware**: include system context as the first message(s) to guide the LLM

see the [MCP Prompts specification](https://modelcontextprotocol.io/specification/draft/server/prompts/) for more details.

### prompt notifications

the server automatically notifies MCP clients when the list of prompts or tools changes. this is handled through the MCP change notifications protocol.

**supported notifications**:
- `prompts/list_changed` - fired when prompts are added or removed
- `tools/list_changed` - fired when tools are added or removed (via ToolManager)

clients can subscribe to these notifications to refresh their prompt/tool lists dynamically. this is useful for:
- dynamic tool registration (see `ToolManager` in Issue #12)
- conditional prompts/tools based on environment variables
- future resource management

**for developers**: to send a notification when you add/remove prompts or tools at runtime, use:

```python
@mcp.tool()
async def refresh_capabilities(ctx: Context) -> str:
    """Notify clients about capability changes."""
    await ctx.send_notification(PromptListChangedNotification())
    # or for tools:
    await ctx.send_notification(ToolListChangedNotification())
    return "Clients notified"
```

see the [MCP specification](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#list-changed-notification) for more details.

## adding new datasets

this project uses a modular dataset system that allows easy addition of new data sources. each dataset is self-contained and automatically discovered by the MCP server.

### dataset structure

each dataset is a python module in `src/point_topic_mcp/context/datasets/` with two required functions:

```python
def get_summary():
    """Brief description visible to agents at all times.
    Keep concise - this goes in every agent prompt."""
    return "short description of what data is available"

def get_full_context():
    """Complete context: schema, instructions, examples.
    Only loaded when agent requests this dataset."""
    return f"""
    {DB_INFO}
    
    {DB_SCHEMA}
    
    {SQL_EXAMPLES}
    """
```

### key principles

1. **context window efficiency**: keep `get_summary()` extremely concise - it's always visible to agents
2. **lazy loading**: full context via `get_full_context()` only loads when needed
3. **self-contained**: each dataset module includes all its own schema, examples, and usage notes
4. **auto-discovery**: new `.py` files in the datasets directory are automatically available

### adding a new dataset

1. **create the module**: `src/point_topic_mcp/context/datasets/your_dataset.py`
2. **implement required functions**: `get_summary()` and `get_full_context()`
3. **test locally**: `uv run mcp dev src/point_topic_mcp/server_local.py`
4. **verify discovery**: agent should see your dataset in `assemble_dataset_context()` tool description

see existing modules (`upc.py`, `upc_take_up.py`, `upc_forecast.py`) for structure examples.

### optimization tips

- prioritize essential info in summaries
- use clear table descriptions that help agents choose the right dataset
- include common query patterns in ClickHouse SQL
- sanity check data against known UK facts in instructions
- the ontology data model is always visible in `execute_query`'s description — datasets are supplementary

## publishing to PyPI (for maintainers)

**build and test locally**:

```bash
# Build the package with UV (super fast!)
uv build

# Test installation locally
pip install dist/point_topic_mcp-*.whl

# Test the command works
point-topic-mcp
```

**publish to PyPI**:

Point Topic developers: authenticate with AWS, then either run (overwrites `~/.pypirc` if it exists - back up first if you have other tokens):

```bash
aws secretsmanager get-secret-value --secret-id pypirc --query SecretString --output text > ~/.pypirc
```

or manually copy the secret from AWS Secrets Manager into `~/.pypirc`.

then publish:

```bash
./publish_to_pypi.sh
```

**test installation from PyPI**:

```bash
pip install point-topic-mcp
point-topic-mcp
```