# MXCP Expert Claude Skill

A comprehensive Claude skill for working with MXCP (Enterprise MCP Framework) - enabling you to build production-ready MCP servers with SQL and Python endpoints, complete with security, audit trails, and policy enforcement.

## What's Included

This skill provides complete guidance for:

- **Creating MXCP projects** - Initialize and structure production-ready MCP servers
- **Endpoint development** - Build tools, resources, and prompts using SQL or Python
- **Enterprise features** - Implement authentication, policies, and audit logging
- **dbt integration** - Combine data transformation with MCP endpoints
- **Quality assurance** - Validate, test, lint, and evaluate your endpoints
- **Production deployment** - Monitor drift, track operations, and ensure security

## Installation

1. Download the `mxcp-expert.zip` file
2. In Claude Desktop, go to Settings → Developer → Custom Skills
3. Click "Add Skill" and upload the `mxcp-expert.zip` file
4. The skill will be automatically available when working on MXCP projects

## Skill Structure

```
mxcp-expert/
├── SKILL.md                                # Main skill file with quick reference
├── assets/                                 # Project templates and resources
│   ├── project-templates/                  # Pre-built MXCP projects
│   │   ├── google-calendar/                # OAuth integration examples
│   │   ├── jira/ jira-oauth/               # Jira integrations
│   │   ├── salesforce/ salesforce-oauth/   # Salesforce integrations
│   │   ├── confluence/                     # Confluence integration
│   │   ├── python-demo/                    # Python endpoint patterns
│   │   ├── covid_owid/                     # dbt data caching example
│   │   ├── keycloak/                       # SSO integration
│   │   └── ...                             # More templates
│   └── schemas/                            # JSON Schema definitions for YAML validation
│       ├── mxcp-site-schema-1.json         # mxcp-site.yml validation
│       ├── mxcp-config-schema-1.json       # config.yml validation
│       ├── tool-schema-1.json              # Tool definition validation
│       ├── resource-schema-1.json          # Resource definition validation
│       ├── prompt-schema-1.json            # Prompt definition validation
│       ├── eval-schema-1.json              # Evaluation suite validation
│       └── common-types-schema-1.json      # Common type definitions
├── scripts/                                # Utility scripts
│   └── validate_yaml.py                    # YAML validation script
└── references/                             # Detailed documentation (23 files)
    ├── tool-templates.md                   # Ready-to-use YAML templates for tools/resources/prompts
    ├── project-selection-guide.md          # Decision tree and template selection
    ├── dbt-core-guide.md                   # Essential dbt knowledge (seeds, models, Python models)
    ├── duckdb-essentials.md                # DuckDB features and SQL extensions
    ├── endpoint-patterns.md                # Complete endpoint examples
    ├── python-api.md                       # Python runtime API reference
    ├── policies.md                         # Policy enforcement guide
    ├── comprehensive-testing-guide.md      # Complete testing strategies
    ├── debugging-guide.md                  # Systematic debugging workflows
    ├── error-handling-guide.md             # Python error handling patterns
    ├── dbt-patterns.md                     # Advanced dbt integration patterns
    ├── database-connections.md             # PostgreSQL, MySQL, SQLite, SQL Server
    ├── excel-integration.md                # Excel file handling with pandas and dbt
    ├── claude-desktop.md                   # Claude Desktop setup guide
    ├── cli-reference.md                    # Complete CLI documentation
    ├── type-system.md                      # Type validation reference
    └── ...                                 # 8 more specialized guides
```

## When This Skill is Used

Claude will automatically use this skill for ANY mention or reference to MXCP, including when you:

- Mention "MXCP", "mxcp", "MXCP server", "MXCP project" in any context
- Ask questions about MXCP or its features
- Create, initialize, build, or set up MXCP projects
- Edit or modify MXCP files (mxcp-site.yml, config.yml, tools/resources/prompts)
- Define or work with MCP tools, resources, or prompts using MXCP
- Implement SQL queries or Python endpoints for MXCP
- Configure MXCP features (authentication, policies, audit logging, dbt integration)
- Run MXCP commands (mxcp validate, mxcp test, mxcp serve, mxcp init, mxcp lint)
- Test, validate, lint, or debug MXCP endpoints
- Fix MXCP validation errors or troubleshoot issues
- Deploy MXCP servers to production

## Quick Start Examples

### Example 1: CSV File to MCP Server

```
User: "I need to connect my chat to a CSV file with customer data"

Claude: [Uses mxcp-expert skill]
I'll help you create an MXCP server that queries your CSV file.

1. Initialize project:
   mkdir customer-mcp && cd customer-mcp
   mxcp init --bootstrap

2. Add your CSV as a dbt seed:
   cp customers.csv seeds/

3. Create schema definition (seeds/schema.yml):
   [Creates proper schema.yml with column types and tests]

4. Load data:
   dbt seed
   dbt test

5. Create query tool:
   [Creates tools/get_customers.yml with parameterized SQL]

6. Test and validate:
   mxcp validate && mxcp test
   mxcp serve

[Provides complete security-first implementation with validation]
```

### Example 2: API Integration

```
User: "Connect to Google Calendar API"

Claude: [Uses mxcp-expert skill]
I'll use the google-calendar project template for OAuth integration.

1. Copy template:
   cp -r assets/project-templates/google-calendar calendar-mcp
   cd calendar-mcp

2. Configure OAuth in project config.yml:
   [Creates config.yml with OAuth settings in project directory]

3. Test authentication:
   mxcp serve
   [Explains OAuth flow]

[Provides complete working OAuth integration]
```

### Example 3: Database Connection

```
User: "Connect to my PostgreSQL production database"

Claude: [Uses mxcp-expert skill]
I'll help you connect to your PostgreSQL database using DuckDB ATTACH.

1. Create project and config:
   mkdir postgres-mcp && cd postgres-mcp
   mxcp init --bootstrap

   Create config.yml with database credentials (uses environment variables)

2. Create SQL tool with ATTACH:
   [Creates tools/query_customers.yml with PostgreSQL ATTACH statement]

3. Set credentials and test:
   export DB_HOST="localhost" DB_USER="readonly_user" DB_PASSWORD="xxx"
   mxcp validate && mxcp run tool query_customers

4. Alternative: Cache data with dbt for fast queries
   [Shows dbt source + model pattern to materialize data]

[Provides both direct query and cached approaches with security best practices]
```

## Key Features Covered

### Endpoint Development
- SQL tools for data queries
- Python tools for complex logic
- Resources for data access
- Prompts with Jinja templates
- Combined SQL + Python patterns

### Enterprise Features
- OAuth authentication (GitHub, Google, Microsoft, etc.)
- Policy-based access control with CEL expressions
- Comprehensive audit logging (JSONL format)
- Field-level data filtering and masking
- User context testing

### Quality Assurance
- Structure validation with `mxcp validate`
- Functional testing with `mxcp test`
- Metadata quality checks with `mxcp lint`
- LLM behavior testing with `mxcp evals`

### dbt Integration
- Data transformation pipelines
- External data caching
- Incremental model patterns
- Data quality tests

### Production Operations
- Drift detection and monitoring
- Audit log querying and export
- Multi-environment profiles
- Secrets management (Vault, 1Password)
- OpenTelemetry observability

## Core Principles

This skill prioritizes:

1. **Security First** - Authentication, authorization, parameterized queries, input validation
2. **Robustness** - Error handling, type safety, data quality checks
3. **Validity** - Schema compliance, structure validation
4. **Testability** - Comprehensive test coverage
5. **Testing** - Always validate/test/lint before deployment

## Mandatory Workflow

**To ensure MXCP servers always work correctly, the agent follows:**

1. **Build incrementally** - One tool/component at a time
2. **Validate continuously** - `mxcp validate` after each change
3. **Test before proceeding** - `mxcp test` must pass before next step
4. **Verify manually** - Run actual tool with real data
5. **Definition of Done** - ALL validation checks must pass

The agent will NEVER declare a project complete unless all validation, tests, and manual verification succeed.

## Documentation Coverage

The skill includes comprehensive documentation based on official MXCP docs:

**CRITICAL - Start Here**:
- **build-and-validate-workflow.md** - MANDATORY workflow ensuring correctness
- **minimal-working-examples.md** - Guaranteed-to-work examples (copy, test, customize)

**Essential Guides** (for most projects):
- **project-selection-guide.md** - Decision trees, heuristics, when to use which approach
- **dbt-core-guide.md** - dbt seeds, models, schema.yml (critical for CSV/data projects)
- **duckdb-essentials.md** - DuckDB SQL features, CSV import, analytics
- **excel-integration.md** - Excel file handling and pandas integration
- **synthetic-data-patterns.md** - Generate test data with GENERATE_SERIES

**Detailed References**:
- **endpoint-patterns.md** - Complete tool/resource/prompt examples
- **python-api.md** - Python runtime API and library wrapping patterns
- **testing-guide.md** - Comprehensive testing strategies
- **policies.md** - Policy enforcement and security
- **type-system.md** - Type validation rules
- **cli-reference.md** - Complete CLI documentation
- **claude-desktop.md** - Claude Desktop integration
- **dbt-patterns.md** - Advanced dbt integration patterns

## About MXCP

MXCP is an enterprise-grade MCP (Model Context Protocol) framework that provides a structured methodology for building production AI applications:

1. **Data Quality First** - Start with dbt models and data contracts
2. **Service Design** - Define types, security policies, and API contracts
3. **Smart Implementation** - Choose SQL for data, Python for logic
4. **Quality Assurance** - Validate, test, lint, and evaluate
5. **Production Operations** - Monitor drift, track audits, ensure performance

## License

This skill compiles information from the MXCP project documentation.
MXCP is released under the Business Source License 1.1 (BSL).

For more information about MXCP:
- Website: https://mxcp.dev
- GitHub: https://github.com/raw-labs/mxcp
- Contact: mxcp@raw-labs.com

## Skill Version

Version: 1.0.0
Created: October 2025
Based on: MXCP documentation as of October 2025