@aborruso/ckan-mcp-server 0.4.16 → 0.4.18

package/REFACTORING.md

@@ -1,238 +0,0 @@
-# Refactoring Documentation
-
-## Overview
-
-Il codebase è stato refactorizzato da un singolo file monolitico di 1021 righe a una struttura modulare di 11 file.
-
-## Motivazione
-
-**Problemi del file unico**:
-- 1021 righe difficili da navigare
-- Modifiche rischiose (alta probabilità di errori)
-- Testing complesso
-- Code review difficili
-- Merge conflicts probabili in collaborazione
-
-**Vantaggi della struttura modulare**:
-- File più piccoli (max 350 righe)
-- Modifiche localizzate e sicure
-- Testing isolato per tool
-- Manutenzione semplificata
-- Collaborazione efficiente
-
-## Nuova Struttura
-
-```
-src/
-├── index.ts              # Entry point (39 lines)
-├── server.ts             # MCP server setup (12 lines)
-├── types.ts              # Types & schemas (16 lines)
-├── utils/
-│   ├── http.ts           # CKAN API client (51 lines)
-│   └── formatting.ts     # Output formatting (37 lines)
-├── tools/
-│   ├── package.ts        # Package tools (350 lines)
-│   ├── organization.ts   # Organization tools (341 lines)
-│   ├── datastore.ts      # DataStore tools (146 lines)
-│   └── status.ts         # Status tools (66 lines)
-└── transport/
-    ├── stdio.ts          # Stdio transport (12 lines)
-    └── http.ts           # HTTP transport (27 lines)
-```
-
-**Total**: 1097 lines (vs 1021 original, +76 lines for better organization)
-
-## File Descriptions
-
-### Core Files
-
-**`index.ts`** (Entry Point)
-- Importa e registra tutti i tool
-- Sceglie transport (stdio/http)
-- Gestisce startup e error handling
-
-**`server.ts`** (Server Configuration)
-- Crea istanza MCP server
-- Configurazione base (name, version)
-
-**`types.ts`** (Type Definitions)
-- `ResponseFormat` enum
-- `ResponseFormatSchema` Zod validator
-- `CHARACTER_LIMIT` constant
-
-### Utils
-
-**`utils/http.ts`** (HTTP Client)
-- `makeCkanRequest<T>()` - HTTP client per CKAN API
-- Normalizzazione URL
-- Gestione errori (timeout, 404, network)
-- User-Agent header
-
-**`utils/formatting.ts`** (Output Formatting)
-- `truncateText()` - Limita output a CHARACTER_LIMIT
-- `formatDate()` - Format date in ISO `YYYY-MM-DD`
-- `formatBytes()` - Human-readable file sizes
-
-### Tools
-
-**`tools/package.ts`** (Package/Dataset Tools)
-- `ckan_package_search` - Search datasets (182 lines handler)
-- `ckan_package_show` - Dataset details (138 lines handler)
-
-**`tools/organization.ts`** (Organization Tools)
-- `ckan_organization_list` - List organizations (118 lines)
-- `ckan_organization_show` - Org details (95 lines)
-- `ckan_organization_search` - Search orgs (102 lines)
-
-**`tools/datastore.ts`** (DataStore Tools)
-- `ckan_datastore_search` - Query tabular data (130 lines)
-
-**`tools/status.ts`** (Status Tools)
-- `ckan_status_show` - Check server status (51 lines)
-
-### Transport
-
-**`transport/stdio.ts`** (Stdio Transport)
-- `runStdio()` - Standard input/output transport
-- For Claude Desktop and local MCP clients
-
-**`transport/http.ts`** (HTTP Transport)
-- `runHTTP()` - HTTP server on configurable port
-- Single shared transport per process
-- For remote access via HTTP POST
-
-## Build Configuration
-
-**No changes needed** - esbuild continua a funzionare:
-```bash
-npm run build  # 15ms build time
-```
-
-esbuild automaticamente:
-- Bundle tutti i moduli interni
-- Tree-shake codice non usato
-- Mantiene external dependencies separate
-- Produce singolo file `dist/index.js`
-
-## Testing Results
-
-✅ **Build**: Successful (15ms)
-✅ **Tool Registration**: All 7 tools listed
-✅ **Tool Execution**: `ckan_status_show` tested successfully
-✅ **Backward Compatibility**: 100% - stessa API MCP
-
-## Benefits Achieved
-
-### Maintainability
-- Ogni file < 350 righe (easy to understand)
-- Moduli isolati (modifiche localizzate)
-- Clear separation of concerns
-
-### Testing
-- Tool handlers isolati e testabili
-- Utilities testabili indipendentemente
-- Mock più facili per unit tests
-
-### Collaboration
-- Merge conflicts ridotti
-- Code review più veloci
-- Feature development parallelo possibile
-
-### Performance
-- Build time invariato: ~15ms
-- Bundle size invariato: ~30KB
-- Runtime performance identico
-- Tree-shaking preservato
-
-## Migration Notes
-
-### Old Structure
-```typescript
-// src/index.ts (1021 lines)
-// Everything in one file
-```
-
-### New Structure
-```typescript
-// src/index.ts (39 lines)
-import { createServer } from "./server.js";
-import { registerPackageTools } from "./tools/package.js";
-// ...
-
-const server = createServer();
-registerPackageTools(server);
-// ...
-```
-
-### Backward Compatibility
-
-✅ **Zero breaking changes**:
-- Stessi tool MCP esposti
-- Stessi parametri input
-- Stesso formato output
-- Stesso comportamento
-
-### Old File Preserved
-
-`src/index-old.ts` - Backup del file originale (per riferimento)
-
-## Future Enhancements Enabled
-
-Con la nuova struttura diventa più facile:
-
-1. **Unit Testing**: Test singoli tool in isolamento
-2. **New Tools**: Aggiungere tool in file separati
-3. **Shared Logic**: Utilities riutilizzabili
-4. **Documentation**: JSDoc per ogni modulo
-5. **Type Safety**: Types centralizzati
-6. **Optimization**: Ottimizzare singoli moduli
-
-## Maintenance Guide
-
-### Adding a New Tool
-
-1. Create `src/tools/newtool.ts`:
-```typescript
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-
-export function registerNewTools(server: McpServer) {
-  server.registerTool("tool_name", { ... }, async (params) => { ... });
-}
-```
-
-2. Import in `src/index.ts`:
-```typescript
-import { registerNewTools } from "./tools/newtool.js";
-registerNewTools(server);
-```
-
-3. Build and test:
-```bash
-npm run build
-npm start
-```
-
-### Modifying a Tool
-
-1. Edit relevant file in `src/tools/`
-2. Changes are isolated
-3. Build and test
-4. No risk to other tools
-
-### Adding Utilities
-
-1. Create in `src/utils/`
-2. Export function
-3. Import where needed
-4. Automatic tree-shaking if unused
-
-## Conclusion
-
-Il refactoring è stato completato con successo:
-- ✅ Struttura modulare
-- ✅ Build funzionante
-- ✅ Backward compatible
-- ✅ Testing verificato
-- ✅ Performance preserved
-
-Il codice è ora più manutenibile, testabile e scalabile, mantenendo tutta la funzionalità originale.

package/examples/langgraph/01_basic_workflow.py

@@ -1,277 +0,0 @@
-#!/usr/bin/env python3
-"""
-Basic LangGraph Workflow with CKAN MCP Server
-
-Demonstrates simple sequential workflow:
-1. Search datasets by keyword
-2. Filter by metadata quality using scoring system
-3. Extract CSV resources
-4. Display results
-
-Run:
-    uvx --with langgraph --with mcp --with langchain-core python 01_basic_workflow.py
-"""
-
-import asyncio
-import json
-import os
-from typing import Annotated, TypedDict
-
-from langgraph.graph import StateGraph, START, END
-from langgraph.graph.message import add_messages
-from mcp import ClientSession, StdioServerParameters
-from mcp.client.stdio import stdio_client
-
-from metadata_quality import MetadataQualityScorer
-
-# Configuration
-CKAN_SERVER = "https://www.dati.gov.it/opendata"
-MCP_SERVER_PATH = os.path.join(os.path.dirname(__file__), "../../dist/index.js")
-QUALITY_THRESHOLD = 40  # Minimum quality score (0-100)
-SEARCH_ROWS = 5  # Limit rows to avoid JSON truncation in MCP responses
-
-
-# State definition
-class WorkflowState(TypedDict):
-    """State tracked through workflow."""
-
-    messages: Annotated[list, add_messages]
-    query: str
-    datasets: list[dict]
-    filtered_datasets: list[dict]
-    csv_resources: list[dict]
-    error: str | None
-
-
-# MCP Client helper
-class CKANMCPClient:
-    """Helper for calling CKAN MCP Server tools."""
-
-    def __init__(self, session: ClientSession):
-        self.session = session
-
-    async def search_packages(self, query: str, rows: int = SEARCH_ROWS) -> dict:
-        """Search CKAN packages."""
-        result = await self.session.call_tool(
-            "ckan_package_search",
-            arguments={
-                "server_url": CKAN_SERVER,
-                "q": query,
-                "rows": rows,
-                "response_format": "json",
-            },
-        )
-
-        # Parse JSON from text content
-        for content in result.content:
-            if content.type == "text":
-                try:
-                    text = content.text
-                    # Handle truncation marker if present
-                    if "[Response truncated" in text:
-                        text = text.split("[Response truncated")[0].strip()
-                    return json.loads(text)
-                except json.JSONDecodeError as e:
-                    return {"error": f"JSON parse error: {e}"}
-
-        return {"error": "No content in response"}
-
-
-# Workflow nodes
-async def search_datasets_node(
-    state: WorkflowState, mcp_client: CKANMCPClient
-) -> WorkflowState:
-    """Node 1: Search datasets."""
-    print(f"\n[1/3] Searching datasets for: '{state['query']}'")
-
-    try:
-        response = await mcp_client.search_packages(state["query"])
-
-        if "error" in response:
-            state["error"] = response["error"]
-            print(f"   ✗ Error: {response['error']}")
-            return state
-
-        if "results" in response:
-            datasets = response["results"]
-            state["datasets"] = datasets
-            state["messages"].append(
-                {"role": "assistant", "content": f"Found {len(datasets)} datasets"}
-            )
-            print(
-                f"   ✓ Found {response.get('count', len(datasets))} total, showing {len(datasets)}"
-            )
-        else:
-            state["error"] = "Unexpected response structure"
-            print(f"   ✗ Error: missing 'results' key")
-
-    except Exception as e:
-        state["error"] = str(e)
-        print(f"   ✗ Error: {e}")
-
-    return state
-
-
-async def filter_quality_node(state: WorkflowState) -> WorkflowState:
-    """Node 2: Filter by metadata quality using scoring system."""
-    print("\n[2/3] Filtering by metadata quality")
-
-    if state.get("error"):
-        return state
-
-    scorer = MetadataQualityScorer()
-    filtered = []
-
-    for ds in state["datasets"]:
-        quality = scorer.score_dataset(ds)
-        ds["_quality"] = quality  # Attach quality info to dataset
-
-        if quality["score"] >= QUALITY_THRESHOLD:
-            filtered.append(ds)
-            print(
-                f"   ✓ {ds['title'][:50]}: {quality['score']}/100 ({quality['level']})"
-            )
-        else:
-            print(f"   ✗ {ds['title'][:50]}: {quality['score']}/100 (rejected)")
-
-    state["filtered_datasets"] = filtered
-    state["messages"].append(
-        {
-            "role": "assistant",
-            "content": f"Filtered to {len(filtered)} quality datasets",
-        }
-    )
-    print(
-        f"\n   → {len(filtered)}/{len(state['datasets'])} datasets pass quality threshold ({QUALITY_THRESHOLD})"
-    )
-
-    return state
-
-    # Filter: must have title, notes, and at least one resource
-    filtered = [
-        ds
-        for ds in state["datasets"]
-        if ds.get("title") and ds.get("notes") and ds.get("num_resources", 0) > 0
-    ]
-
-    state["filtered_datasets"] = filtered
-    state["messages"].append(
-        {
-            "role": "assistant",
-            "content": f"Filtered to {len(filtered)} quality datasets",
-        }
-    )
-    print(f"   ✓ {len(filtered)} datasets with good metadata")
-
-    return state
-
-
-async def extract_csv_node(state: WorkflowState) -> WorkflowState:
-    """Node 3: Extract CSV resources."""
-    print("\n[3/3] Extracting CSV resources")
-
-    if state.get("error"):
-        return state
-
-    csv_resources = []
-    for dataset in state["filtered_datasets"][:5]:  # Limit to first 5
-        for resource in dataset.get("resources", []):
-            if resource.get("format", "").lower() == "csv":
-                csv_resources.append(
-                    {
-                        "dataset_name": dataset["name"],
-                        "dataset_title": dataset["title"],
-                        "resource_name": resource.get("name", "Untitled"),
-                        "url": resource.get("url"),
-                    }
-                )
-
-    state["csv_resources"] = csv_resources
-    state["messages"].append(
-        {
-            "role": "assistant",
-            "content": f"Extracted {len(csv_resources)} CSV resources",
-        }
-    )
-    print(f"   ✓ Found {len(csv_resources)} CSV resources")
-
-    return state
-
-
-# Build graph
-async def build_workflow(mcp_client: CKANMCPClient) -> StateGraph:
-    """Build LangGraph workflow."""
-    graph = StateGraph(WorkflowState)
-
-    # Add nodes - wrap async functions properly
-    async def search_wrapper(state: WorkflowState) -> WorkflowState:
-        return await search_datasets_node(state, mcp_client)
-
-    graph.add_node("search", search_wrapper)
-    graph.add_node("filter", filter_quality_node)
-    graph.add_node("extract", extract_csv_node)
-
-    # Define edges
-    graph.add_edge(START, "search")
-    graph.add_edge("search", "filter")
-    graph.add_edge("filter", "extract")
-    graph.add_edge("extract", END)
-
-    return graph.compile()
-
-
-async def main():
-    """Run workflow."""
-    print("=" * 60)
-    print("LangGraph + CKAN MCP Server - Basic Workflow")
-    print("=" * 60)
-
-    # Connect to MCP server
-    server_params = StdioServerParameters(command="node", args=[MCP_SERVER_PATH])
-
-    async with stdio_client(server_params) as (read, write):
-        async with ClientSession(read, write) as session:
-            await session.initialize()
-            print("\n✓ Connected to CKAN MCP Server")
-
-            # Build workflow
-            mcp_client = CKANMCPClient(session)
-            workflow = await build_workflow(mcp_client)
-
-            # Execute workflow
-            initial_state: WorkflowState = {
-                "messages": [],
-                "query": "mobilità urbana",
-                "datasets": [],
-                "filtered_datasets": [],
-                "csv_resources": [],
-                "error": None,
-            }
-
-            result = await workflow.ainvoke(initial_state)
-
-            # Display results
-            print("\n" + "=" * 60)
-            print("RESULTS")
-            print("=" * 60)
-
-            if result["error"]:
-                print(f"\n✗ Workflow failed: {result['error']}")
-            else:
-                print(f"\nQuery: {result['query']}")
-                print(f"Total datasets found: {len(result['datasets'])}")
-                print(f"Quality datasets: {len(result['filtered_datasets'])}")
-                print(f"CSV resources: {len(result['csv_resources'])}")
-
-                if result["csv_resources"]:
-                    print("\nFirst 3 CSV resources:")
-                    for i, res in enumerate(result["csv_resources"][:3], 1):
-                        print(f"\n{i}. {res['resource_name']}")
-                        print(f"   Dataset: {res['dataset_title']}")
-                        print(f"   URL: {res['url']}")
-
-            print("\n" + "=" * 60)
-
-
-if __name__ == "__main__":
-    asyncio.run(main())