zhongwei/gh-raw-labs-claude-code-marketplace-claude-plugin-plugins-mxcp-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:49:50 +08:00
commit adc4b2be25
147 changed files with 24716 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

273
skills/mxcp-expert/README.md Normal file
View File

@@ -0,0 +1,273 @@
# 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