Initial commit

2025-11-30 08:49:50 +08:00
commit adc4b2be25
147 changed files with 24716 additions and 0 deletions
--- a/skills/mxcp-expert/assets/project-templates/covid_owid/README.md
+++ b/skills/mxcp-expert/assets/project-templates/covid_owid/README.md
@@ -0,0 +1,149 @@
+# COVID-19 OWID Example
+
+This example demonstrates how to use MXCP to create a COVID-19 data analysis API. It shows how to:
+- Fetch and cache COVID-19 data from Our World in Data (OWID)
+- Transform data using dbt and DuckDB
+- Create a natural language interface for data exploration using generic SQL tools
+
+## Features
+
+- **Comprehensive Data**: Global COVID-19 statistics from OWID
+- **Data Transformation**: dbt models for efficient querying
+- **Natural Language**: LLM-friendly query interface (prompt only)
+
+## Getting Started
+
+### Prerequisites
+
+Make sure you have the required tools installed:
+```bash
+# Install MXCP and dependencies
+pip install mxcp dbt-core dbt-duckdb
+
+# Option: Install in development mode
+cd /path/to/mxcp
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+### Running the Example
+
+1. Navigate to the COVID example:
+   ```bash
+   cd examples/covid_owid
+   ```
+
+2. Initialize the data:
+   ```bash
+   dbt deps
+   dbt run
+   ```
+
+3. Start the MCP server:
+   ```bash
+   mxcp serve
+   ```
+
+## 🔌 Claude Desktop Integration
+
+To use this example with Claude Desktop:
+
+### 1. Locate Claude's Configuration
+
+Find your Claude Desktop configuration file:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+### 2. Configure the MCP Server
+
+Add this configuration to your `claude_desktop_config.json`:
+
+#### If you installed MXCP globally:
+```json
+{
+  "mcpServers": {
+    "covid": {
+      "command": "mxcp",
+      "args": ["serve", "--transport", "stdio"],
+      "cwd": "/absolute/path/to/mxcp/examples/covid_owid"
+    }
+  }
+}
+```
+
+#### If you're using a virtual environment:
+```json
+{
+  "mcpServers": {
+    "covid": {
+      "command": "/bin/bash",
+      "args": [
+        "-c",
+        "cd /absolute/path/to/mxcp/examples/covid_owid && source ../../.venv/bin/activate && mxcp serve --transport stdio"
+      ]
+    }
+  }
+}
+```
+
+**Important**: Replace `/absolute/path/to/mxcp` with the actual path to your MXCP installation.
+
+### 3. Restart Claude Desktop
+
+After saving the configuration, restart Claude Desktop to load the new MCP server.
+
+### 4. Test the Integration
+
+In Claude Desktop, try asking:
+- "Show me COVID-19 cases in the United States for 2022"
+- "Compare vaccination rates between France and Germany"
+- "What were the peak hospitalization rates in the UK?"
+
+## 🛠️ Other MCP Clients
+
+This example works with any MCP-compatible tool:
+- **mcp-cli**: Interactive command-line interface
+- **Custom integrations**: Build your own using the MCP specification
+
+## Example Usage
+
+The LLM can help you analyze:
+- Case numbers and death rates
+- Vaccination progress
+- Hospital occupancy
+- Regional comparisons
+- Policy effectiveness
+
+All queries are handled through the generic SQL query interface. You can:
+- Use `list_tables` to see available tables
+- Use `get_table_schema` to inspect table structure
+- Use `execute_sql_query` to run custom SQL queries
+
+## Implementation Details
+
+The example uses:
+- dbt for data transformation
+- DuckDB for efficient storage and querying
+- SQL analytics for complex calculations
+- Type-safe parameters for filtering
+
+## Project Structure
+
+```
+covid_owid/
+├── endpoints/                # MCP endpoint definitions
+│   └── prompt.yml           # LLM system prompt (generic query interface only)
+├── models/                  # dbt transformations
+│   ├── covid_data.sql      # Main COVID-19 statistics
+│   ├── hospitalizations.sql # Hospital/ICU data
+│   └── locations.sql       # Geographic data
+├── mxcp-site.yml           # MCP configuration
+└── dbt_project.yml         # dbt configuration
+```
+
+## Learn More
+
+- [OWID COVID-19 Data](https://github.com/owid/covid-19-data) - Data source
+- [dbt Documentation](https://docs.getdbt.com/) - Data transformation
+- [DuckDB Documentation](https://duckdb.org/docs/) - Database engine
+- [MXCP Documentation](../../docs/quickstart.md) - MCP framework