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/earthquakes/README.md
+++ b/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