Initial commit

skills/mxcp-expert/assets/project-templates/earthquakes/README.md

@@ -0,0 +1,139 @@
+# Earthquakes Example
+
+This example demonstrates how to use MXCP to create a real-time earthquake data API. It shows how to:
+- Query live earthquake data from the USGS API
+- Transform JSON data using SQL
+- Create type-safe endpoints for LLM consumption
+
+## Features
+
+- **Real-time Data**: Fetches the latest earthquake data from USGS
+- **Type Safety**: Strong typing for LLM safety
+- **SQL Transformations**: Complex JSON parsing and data transformation
+- **Test Coverage**: Includes example tests
+
+## Getting Started
+
+### Prerequisites
+
+Make sure you have MXCP installed:
+```bash
+# Option 1: Install globally
+pip install mxcp
+
+# Option 2: Install in development mode (if you cloned the repo)
+cd /path/to/mxcp
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+### Running the Example
+
+1. Navigate to the earthquakes example:
+   ```bash
+   cd examples/earthquakes
+   ```
+
+2. 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": {
+    "earthquakes": {
+      "command": "mxcp",
+      "args": ["serve", "--transport", "stdio"],
+      "cwd": "/absolute/path/to/mxcp/examples/earthquakes"
+    }
+  }
+}
+```
+
+#### If you're using a virtual environment:
+```json
+{
+  "mcpServers": {
+    "earthquakes": {
+      "command": "/bin/bash",
+      "args": [
+        "-c",
+        "cd /absolute/path/to/mxcp/examples/earthquakes && 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 recent earthquakes above magnitude 5.0"
+- "What was the strongest earthquake in the last 24 hours?"
+- "List earthquakes near California"
+
+Claude will automatically use the earthquake data tools to answer your questions.
+
+## 🛠️ Other MCP Clients
+
+This example also works with other MCP-compatible tools:
+
+- **mcp-cli**: `pip install mcp-cli` then use the same server config
+- **Custom integrations**: Use the MCP specification to build your own client
+
+## Example Usage
+
+Ask your LLM to:
+- "Show me recent earthquakes above magnitude 5.0"
+- "What was the strongest earthquake in the last 24 hours?"
+- "List earthquakes near [location]"
+
+## Implementation Details
+
+The example uses:
+- DuckDB's `read_json_auto` function to parse USGS GeoJSON
+- SQL window functions for data analysis
+- Type-safe parameters for filtering
+
+For more details on:
+- Type system: See [Type System Documentation](../../docs/type-system.md)
+- SQL capabilities: See [Integrations Documentation](../../docs/integrations.md)
+- Configuration: See [Configuration Guide](../../docs/configuration.md)
+
+## Project Structure
+
+```
+earthquakes/
+├── endpoints/
+│   └── tool.yml      # Endpoint definition
+├── mxcp-site.yml     # Project configuration
+└── tests/            # Example tests
+```
+
+## Learn More
+
+- [Quickstart Guide](../../docs/quickstart.md) - Get started with MXCP
+- [CLI Reference](../../docs/cli.md) - Available commands
+- [Configuration](../../docs/configuration.md) - Project setup 

skills/mxcp-expert/assets/project-templates/earthquakes/mxcp-site.yml

@@ -0,0 +1,7 @@
+mxcp: 1
+project: earthquake-api
+profile: prod
+profiles:
+  prod:
+    audit:
+      enabled: true

skills/mxcp-expert/assets/project-templates/earthquakes/prompts/prompt.yml

@@ -0,0 +1,25 @@
+mxcp: 1
+
+prompt:
+  name: "summarize_earthquake_data"
+  description: "Summarizes recent earthquake activity in plain English."
+  tags: ["summary", "earthquake"]
+  parameters:
+    - name: top_event
+      type: string
+      description: "The most significant recent earthquake details as text"
+  messages:
+    - role: system
+      type: text
+      prompt: "You are an expert seismologist summarizing recent activity for the general public."
+    - role: user
+      type: text
+      prompt: |
+        Based on this recent event: {{ top_event }},
+        please provide a brief summary of current seismic activity.
+        Explain the significance of the event in terms of its magnitude and location.
+        Include any additional details that might help the user understand the event.
+        Use simple language and avoid technical terms.
+        Keep it short and concise.
+        Example output:
+        "There was a magnitude 5.5 earthquake in San Francisco yesterday."

skills/mxcp-expert/assets/project-templates/earthquakes/tools/tool.yml

@@ -0,0 +1,52 @@
+mxcp: 1
+
+tool:
+  name: "query_recent_earthquakes"
+  description: "Query earthquakes over a given magnitude threshold."
+  tags: ["earthquake", "filter"]
+  parameters:
+    - name: min_magnitude
+      type: number
+      description: "Minimum magnitude"
+      default: 2.5
+  return:
+    type: array
+    items:
+      type: object
+  source:
+    code: |
+      WITH raw AS (
+        SELECT * FROM read_json_auto('https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_day.geojson')
+      ),
+      features AS (
+        SELECT
+          feature
+        FROM raw,
+            UNNEST(features) AS feature
+      ),
+      quakes AS (
+        SELECT
+          feature -> 'unnest' -> 'properties' -> 'mag' AS magnitude,
+          feature -> 'unnest' -> 'properties' -> 'place' AS location,
+          feature -> 'unnest' -> 'properties' -> 'time' AS time,
+          feature -> 'unnest' -> 'geometry' -> 'coordinates' AS coords
+        FROM features
+      )
+      SELECT
+        CAST(magnitude AS DOUBLE) AS magnitude,
+        location,
+        CAST(time AS BIGINT) AS time,
+        coords
+      FROM quakes
+      WHERE CAST(magnitude AS DOUBLE) >= $min_magnitude
+      ORDER BY magnitude DESC;
+  annotations:
+    title: "Query Significant Earthquakes"
+    readOnlyHint: true
+    idempotentHint: true
+    openWorldHint: true
+  tests:
+    - name: filter-mag
+      arguments:
+        - key: min_magnitude
+          value: 5.5