@maestro-ai/mcp-server 1.0.0 → 1.1.0

package/dist/content/content/skills/python-patterns/SKILL.md

@@ -1,441 +0,0 @@
----
-name: python-patterns
-description: Python development principles and decision-making. Framework selection, async patterns, type hints, project structure. Teaches thinking, not copying.
-allowed-tools: Read, Write, Edit, Glob, Grep
----
-
-# Python Patterns
-
-> Python development principles and decision-making for 2025.
-> **Learn to THINK, not memorize patterns.**
-
----
-
-## ⚠️ How to Use This Skill
-
-This skill teaches **decision-making principles**, not fixed code to copy.
-
-- ASK user for framework preference when unclear
-- Choose async vs sync based on CONTEXT
-- Don't default to same framework every time
-
----
-
-## 1. Framework Selection (2025)
-
-### Decision Tree
-
-```
-What are you building?
-│
-├── API-first / Microservices
-│   └── FastAPI (async, modern, fast)
-│
-├── Full-stack web / CMS / Admin
-│   └── Django (batteries-included)
-│
-├── Simple / Script / Learning
-│   └── Flask (minimal, flexible)
-│
-├── AI/ML API serving
-│   └── FastAPI (Pydantic, async, uvicorn)
-│
-└── Background workers
-    └── Celery + any framework
-```
-
-### Comparison Principles
-
-| Factor | FastAPI | Django | Flask |
-|--------|---------|--------|-------|
-| **Best for** | APIs, microservices | Full-stack, CMS | Simple, learning |
-| **Async** | Native | Django 5.0+ | Via extensions |
-| **Admin** | Manual | Built-in | Via extensions |
-| **ORM** | Choose your own | Django ORM | Choose your own |
-| **Learning curve** | Low | Medium | Low |
-
-### Selection Questions to Ask:
-1. Is this API-only or full-stack?
-2. Need admin interface?
-3. Team familiar with async?
-4. Existing infrastructure?
-
----
-
-## 2. Async vs Sync Decision
-
-### When to Use Async
-
-```
-async def is better when:
-├── I/O-bound operations (database, HTTP, file)
-├── Many concurrent connections
-├── Real-time features
-├── Microservices communication
-└── FastAPI/Starlette/Django ASGI
-
-def (sync) is better when:
-├── CPU-bound operations
-├── Simple scripts
-├── Legacy codebase
-├── Team unfamiliar with async
-└── Blocking libraries (no async version)
-```
-
-### The Golden Rule
-
-```
-I/O-bound → async (waiting for external)
-CPU-bound → sync + multiprocessing (computing)
-
-Don't:
-├── Mix sync and async carelessly
-├── Use sync libraries in async code
-└── Force async for CPU work
-```
-
-### Async Library Selection
-
-| Need | Async Library |
-|------|---------------|
-| HTTP client | httpx |
-| PostgreSQL | asyncpg |
-| Redis | aioredis / redis-py async |
-| File I/O | aiofiles |
-| Database ORM | SQLAlchemy 2.0 async, Tortoise |
-
----
-
-## 3. Type Hints Strategy
-
-### When to Type
-
-```
-Always type:
-├── Function parameters
-├── Return types
-├── Class attributes
-├── Public APIs
-
-Can skip:
-├── Local variables (let inference work)
-├── One-off scripts
-├── Tests (usually)
-```
-
-### Common Type Patterns
-
-```python
-# These are patterns, understand them:
-
-# Optional → might be None
-from typing import Optional
-def find_user(id: int) -> Optional[User]: ...
-
-# Union → one of multiple types
-def process(data: str | dict) -> None: ...
-
-# Generic collections
-def get_items() -> list[Item]: ...
-def get_mapping() -> dict[str, int]: ...
-
-# Callable
-from typing import Callable
-def apply(fn: Callable[[int], str]) -> str: ...
-```
-
-### Pydantic for Validation
-
-```
-When to use Pydantic:
-├── API request/response models
-├── Configuration/settings
-├── Data validation
-├── Serialization
-
-Benefits:
-├── Runtime validation
-├── Auto-generated JSON schema
-├── Works with FastAPI natively
-└── Clear error messages
-```
-
----
-
-## 4. Project Structure Principles
-
-### Structure Selection
-
-```
-Small project / Script:
-├── main.py
-├── utils.py
-└── requirements.txt
-
-Medium API:
-├── app/
-│   ├── __init__.py
-│   ├── main.py
-│   ├── models/
-│   ├── routes/
-│   ├── services/
-│   └── schemas/
-├── tests/
-└── pyproject.toml
-
-Large application:
-├── src/
-│   └── myapp/
-│       ├── core/
-│       ├── api/
-│       ├── services/
-│       ├── models/
-│       └── ...
-├── tests/
-└── pyproject.toml
-```
-
-### FastAPI Structure Principles
-
-```
-Organize by feature or layer:
-
-By layer:
-├── routes/ (API endpoints)
-├── services/ (business logic)
-├── models/ (database models)
-├── schemas/ (Pydantic models)
-└── dependencies/ (shared deps)
-
-By feature:
-├── users/
-│   ├── routes.py
-│   ├── service.py
-│   └── schemas.py
-└── products/
-    └── ...
-```
-
----
-
-## 5. Django Principles (2025)
-
-### Django Async (Django 5.0+)
-
-```
-Django supports async:
-├── Async views
-├── Async middleware
-├── Async ORM (limited)
-└── ASGI deployment
-
-When to use async in Django:
-├── External API calls
-├── WebSocket (Channels)
-├── High-concurrency views
-└── Background task triggering
-```
-
-### Django Best Practices
-
-```
-Model design:
-├── Fat models, thin views
-├── Use managers for common queries
-├── Abstract base classes for shared fields
-
-Views:
-├── Class-based for complex CRUD
-├── Function-based for simple endpoints
-├── Use viewsets with DRF
-
-Queries:
-├── select_related() for FKs
-├── prefetch_related() for M2M
-├── Avoid N+1 queries
-└── Use .only() for specific fields
-```
-
----
-
-## 6. FastAPI Principles
-
-### async def vs def in FastAPI
-
-```
-Use async def when:
-├── Using async database drivers
-├── Making async HTTP calls
-├── I/O-bound operations
-└── Want to handle concurrency
-
-Use def when:
-├── Blocking operations
-├── Sync database drivers
-├── CPU-bound work
-└── FastAPI runs in threadpool automatically
-```
-
-### Dependency Injection
-
-```
-Use dependencies for:
-├── Database sessions
-├── Current user / Auth
-├── Configuration
-├── Shared resources
-
-Benefits:
-├── Testability (mock dependencies)
-├── Clean separation
-├── Automatic cleanup (yield)
-```
-
-### Pydantic v2 Integration
-
-```python
-# FastAPI + Pydantic are tightly integrated:
-
-# Request validation
-@app.post("/users")
-async def create(user: UserCreate) -> UserResponse:
-    # user is already validated
-    ...
-
-# Response serialization
-# Return type becomes response schema
-```
-
----
-
-## 7. Background Tasks
-
-### Selection Guide
-
-| Solution | Best For |
-|----------|----------|
-| **BackgroundTasks** | Simple, in-process tasks |
-| **Celery** | Distributed, complex workflows |
-| **ARQ** | Async, Redis-based |
-| **RQ** | Simple Redis queue |
-| **Dramatiq** | Actor-based, simpler than Celery |
-
-### When to Use Each
-
-```
-FastAPI BackgroundTasks:
-├── Quick operations
-├── No persistence needed
-├── Fire-and-forget
-└── Same process
-
-Celery/ARQ:
-├── Long-running tasks
-├── Need retry logic
-├── Distributed workers
-├── Persistent queue
-└── Complex workflows
-```
-
----
-
-## 8. Error Handling Principles
-
-### Exception Strategy
-
-```
-In FastAPI:
-├── Create custom exception classes
-├── Register exception handlers
-├── Return consistent error format
-└── Log without exposing internals
-
-Pattern:
-├── Raise domain exceptions in services
-├── Catch and transform in handlers
-└── Client gets clean error response
-```
-
-### Error Response Philosophy
-
-```
-Include:
-├── Error code (programmatic)
-├── Message (human readable)
-├── Details (field-level when applicable)
-└── NOT stack traces (security)
-```
-
----
-
-## 9. Testing Principles
-
-### Testing Strategy
-
-| Type | Purpose | Tools |
-|------|---------|-------|
-| **Unit** | Business logic | pytest |
-| **Integration** | API endpoints | pytest + httpx/TestClient |
-| **E2E** | Full workflows | pytest + DB |
-
-### Async Testing
-
-```python
-# Use pytest-asyncio for async tests
-
-import pytest
-from httpx import AsyncClient
-
-@pytest.mark.asyncio
-async def test_endpoint():
-    async with AsyncClient(app=app, base_url="http://test") as client:
-        response = await client.get("/users")
-        assert response.status_code == 200
-```
-
-### Fixtures Strategy
-
-```
-Common fixtures:
-├── db_session → Database connection
-├── client → Test client
-├── authenticated_user → User with token
-└── sample_data → Test data setup
-```
-
----
-
-## 10. Decision Checklist
-
-Before implementing:
-
-- [ ] **Asked user about framework preference?**
-- [ ] **Chosen framework for THIS context?** (not just default)
-- [ ] **Decided async vs sync?**
-- [ ] **Planned type hint strategy?**
-- [ ] **Defined project structure?**
-- [ ] **Planned error handling?**
-- [ ] **Considered background tasks?**
-
----
-
-## 11. Anti-Patterns to Avoid
-
-### ❌ DON'T:
-- Default to Django for simple APIs (FastAPI may be better)
-- Use sync libraries in async code
-- Skip type hints for public APIs
-- Put business logic in routes/views
-- Ignore N+1 queries
-- Mix async and sync carelessly
-
-### ✅ DO:
-- Choose framework based on context
-- Ask about async requirements
-- Use Pydantic for validation
-- Separate concerns (routes → services → repos)
-- Test critical paths
-
----
-
-> **Remember**: Python patterns are about decision-making for YOUR specific context. Don't copy code—think about what serves your application best.

package/dist/content/content/skills/react-patterns/SKILL.md

@@ -1,198 +0,0 @@
----
-name: react-patterns
-description: Modern React patterns and principles. Hooks, composition, performance, TypeScript best practices.
-allowed-tools: Read, Write, Edit, Glob, Grep
----
-
-# React Patterns
-
-> Principles for building production-ready React applications.
-
----
-
-## 1. Component Design Principles
-
-### Component Types
-
-| Type | Use | State |
-|------|-----|-------|
-| **Server** | Data fetching, static | None |
-| **Client** | Interactivity | useState, effects |
-| **Presentational** | UI display | Props only |
-| **Container** | Logic/state | Heavy state |
-
-### Design Rules
-
-- One responsibility per component
-- Props down, events up
-- Composition over inheritance
-- Prefer small, focused components
-
----
-
-## 2. Hook Patterns
-
-### When to Extract Hooks
-
-| Pattern | Extract When |
-|---------|-------------|
-| **useLocalStorage** | Same storage logic needed |
-| **useDebounce** | Multiple debounced values |
-| **useFetch** | Repeated fetch patterns |
-| **useForm** | Complex form state |
-
-### Hook Rules
-
-- Hooks at top level only
-- Same order every render
-- Custom hooks start with "use"
-- Clean up effects on unmount
-
----
-
-## 3. State Management Selection
-
-| Complexity | Solution |
-|------------|----------|
-| Simple | useState, useReducer |
-| Shared local | Context |
-| Server state | React Query, SWR |
-| Complex global | Zustand, Redux Toolkit |
-
-### State Placement
-
-| Scope | Where |
-|-------|-------|
-| Single component | useState |
-| Parent-child | Lift state up |
-| Subtree | Context |
-| App-wide | Global store |
-
----
-
-## 4. React 19 Patterns
-
-### New Hooks
-
-| Hook | Purpose |
-|------|---------|
-| **useActionState** | Form submission state |
-| **useOptimistic** | Optimistic UI updates |
-| **use** | Read resources in render |
-
-### Compiler Benefits
-
-- Automatic memoization
-- Less manual useMemo/useCallback
-- Focus on pure components
-
----
-
-## 5. Composition Patterns
-
-### Compound Components
-
-- Parent provides context
-- Children consume context
-- Flexible slot-based composition
-- Example: Tabs, Accordion, Dropdown
-
-### Render Props vs Hooks
-
-| Use Case | Prefer |
-|----------|--------|
-| Reusable logic | Custom hook |
-| Render flexibility | Render props |
-| Cross-cutting | Higher-order component |
-
----
-
-## 6. Performance Principles
-
-### When to Optimize
-
-| Signal | Action |
-|--------|--------|
-| Slow renders | Profile first |
-| Large lists | Virtualize |
-| Expensive calc | useMemo |
-| Stable callbacks | useCallback |
-
-### Optimization Order
-
-1. Check if actually slow
-2. Profile with DevTools
-3. Identify bottleneck
-4. Apply targeted fix
-
----
-
-## 7. Error Handling
-
-### Error Boundary Usage
-
-| Scope | Placement |
-|-------|-----------|
-| App-wide | Root level |
-| Feature | Route/feature level |
-| Component | Around risky component |
-
-### Error Recovery
-
-- Show fallback UI
-- Log error
-- Offer retry option
-- Preserve user data
-
----
-
-## 8. TypeScript Patterns
-
-### Props Typing
-
-| Pattern | Use |
-|---------|-----|
-| Interface | Component props |
-| Type | Unions, complex |
-| Generic | Reusable components |
-
-### Common Types
-
-| Need | Type |
-|------|------|
-| Children | ReactNode |
-| Event handler | MouseEventHandler |
-| Ref | RefObject<Element> |
-
----
-
-## 9. Testing Principles
-
-| Level | Focus |
-|-------|-------|
-| Unit | Pure functions, hooks |
-| Integration | Component behavior |
-| E2E | User flows |
-
-### Test Priorities
-
-- User-visible behavior
-- Edge cases
-- Error states
-- Accessibility
-
----
-
-## 10. Anti-Patterns
-
-| ❌ Don't | ✅ Do |
-|----------|-------|
-| Prop drilling deep | Use context |
-| Giant components | Split smaller |
-| useEffect for everything | Server components |
-| Premature optimization | Profile first |
-| Index as key | Stable unique ID |
-
----
-
-> **Remember:** React is about composition. Build small, combine thoughtfully.