agent-skill-kit 3.9.135

package/.agent/skills/mcp-builder/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: mcp-builder
+description: >-
+  Build MCP servers for AI agents with design principles and 4-phase build process.
+  Use when creating new MCP servers, designing tool APIs, or evaluating MCP architectures.
+  NOT for using existing MCP tools (use mcp-management).
+category: agent-tooling
+triggers: ["build MCP", "create MCP server", "MCP development", "Model Context Protocol", "agent tools"]
+coordinates_with: ["mcp-management", "api-architect", "typescript-expert"]
+success_metrics: ["100% 4-phase completion", "10 evaluation questions generated"]
+metadata:
+  author: pikakit
+  version: "3.9.134"
+---
+
+# MCP Builder — Build MCP Servers for AI Agents
+
+> 4 phases. Workflow over endpoints. 10-question evaluation. Context-aware output.
+
+---
+
+## Prerequisites
+
+**Required:** Python 3.10+ or Node.js 18+. MCP spec: `https://modelcontextprotocol.io/llms-full.txt`
+
+---
+
+## When to Use
+
+| Situation | Action |
+|-----------|--------|
+| Build a new MCP server | Follow 4-phase process |
+| Choose framework | Python FastMCP vs TypeScript MCP SDK |
+| Review MCP server quality | Use review checklist (4 items) |
+| Test MCP server | Create 10 evaluation questions |
+| Learn MCP design | Read `rules/design-principles.md` |
+
+---
+
+## System Boundaries
+
+| Owned by This Skill | NOT Owned |
+|---------------------|-----------|
+| 4-phase build process | MCP tool discovery (→ mcp-management) |
+| Framework selection (2 options) | API design (→ api-architect) |
+| Review checklist (4 items) | TypeScript patterns (→ typescript-expert) |
+| Evaluation framework (10 questions) | Server hosting/deployment |
+
+**Expert decision skill:** Produces build guidance. Does not create files or run code.
+
+---
+
+## 4-Phase Build Process (Fixed Order)
+
+| Phase | Focus | Deliverable |
+|-------|-------|-------------|
+| 1. **Research** | Study MCP spec + target API | API surface documented |
+| 2. **Implement** | Build with selected framework | Server code complete |
+| 3. **Review** | Quality checklist pass | All 4 items pass |
+| 4. **Evaluate** | 10 complex test questions | All 10 pass |
+
+---
+
+## Framework Selection (Deterministic)
+
+| Condition | Framework |
+|-----------|-----------|
+| Team is python-heavy OR needs_async | **Python FastMCP** |
+| Team is typescript-heavy OR needs strict typing | **TypeScript MCP SDK** |
+| Balanced / no preference | **Python FastMCP** (default) |
+
+---
+
+## Review Checklist (4 Mandatory Items)
+
+- [ ] No duplicate code (DRY)
+- [ ] Error handling for all external calls
+- [ ] Full type coverage
+- [ ] All tools have detailed docstrings
+
+```bash
+# Python verification
+python -m py_compile server.py
+
+# TypeScript verification
+tsc --noEmit
+```
+
+---
+
+## Evaluation Framework
+
+Create 10 test questions that are:
+
+| Criterion | Requirement |
+|-----------|-------------|
+| Independent | No dependencies between questions |
+| Read-only | Never modify data |
+| Complex | Require multi-tool workflows |
+| Realistic | Match real user scenarios |
+| Verifiable | Deterministic expected output |
+| Stable | Consistent results across runs |
+
+---
+
+## Design Principles
+
+| Principle | Application |
+|-----------|-------------|
+| Workflow over endpoints | Design tools for agent tasks, not API mirrors |
+| Context-aware output | Support `concise` vs `detailed` modes |
+| Actionable errors | Error messages include recovery steps |
+
+---
+
+## Error Taxonomy
+
+| Code | Recoverable | Trigger |
+|------|-------------|---------|
+| `ERR_INVALID_REQUEST_TYPE` | No | Request type not supported |
+| `ERR_INVALID_PHASE` | Yes | Phase number not 1-4 |
+| `ERR_MISSING_EXPERIENCE` | Yes | Team experience not provided |
+| `ERR_REFERENCE_NOT_FOUND` | No | Reference file missing |
+
+**Zero internal retries.** Deterministic; same context = same guidance.
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|---------|-------|
+| Mirror API endpoints as tools | Design workflow-oriented tools |
+| Skip evaluation phase | Create 10 test questions |
+| Omit docstrings on tools | Detailed docstrings for agent discovery |
+| Embed API keys in tool code | Use environment variables |
+| Skip research phase | Read MCP spec + target API first |
+
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| [design-principles.md](rules/design-principles.md) | Core MCP concepts | Phase 1 (Research) |
+| [quickstart.md](rules/quickstart.md) | Getting started | Phase 2 (Implement) |
+| [python-implementation.md](rules/python-implementation.md) | Python patterns | Python selected |
+| [typescript-implementation.md](rules/typescript-implementation.md) | TypeScript patterns | TypeScript selected |
+| [best-practices.md](rules/best-practices.md) | Design decisions | Phase 3 (Review) |
+| [evaluation.md](rules/evaluation.md) | Testing framework | Phase 4 (Evaluate) |
+| [engineering-spec.md](rules/engineering-spec.md) | Full engineering spec | Architecture review |
+
+**Selective reading:** Read ONLY files relevant to the current phase.
+
+---
+
+## 🔗 Related
+
+| Item | Type | Purpose |
+|------|------|---------|
+| `mcp-management` | Skill | MCP tool discovery |
+| `api-architect` | Skill | API design |
+| `typescript-expert` | Skill | TS patterns |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/mcp-builder/rules/_sections.md

@@ -0,0 +1,40 @@
+# Sections
+
+This file defines all sections, their ordering, impact levels, and descriptions.
+The section ID (in parentheses) is the filename prefix used to group rules.
+
+---
+
+## 1. General (general)
+
+**Impact:** LOW  
+**Description:** General patterns and best practices.
+
+## 2. Best (best)
+
+**Impact:** LOW  
+**Description:** Best patterns and best practices.
+
+## 3. Design (design)
+
+**Impact:** LOW  
+**Description:** Design patterns and best practices.
+
+## 4. Engineering Specification (engineering)
+
+**Impact:** MEDIUM  
+**Description:** Full engineering specification covering contracts, security, and scalability.
+
+## 5. Python (python)
+
+**Impact:** LOW  
+**Description:** Python patterns and best practices.
+
+## 6. Typescript (typescript)
+
+**Impact:** LOW  
+**Description:** Typescript patterns and best practices.
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/mcp-builder/rules/_template.md

@@ -0,0 +1,32 @@
+---
+title: Rule Title Here
+impact: MEDIUM
+impactDescription: Optional description of impact (e.g., "20-50% improvement")
+tags: tag1, tag2
+---
+
+## Rule Title Here
+
+**Impact: MEDIUM (optional impact description)**
+
+Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
+
+**Incorrect (description of what's wrong):**
+
+```typescript
+// Bad code example here
+const bad = example()
+```
+
+**Correct (description of what's right):**
+
+```typescript
+// Good code example here
+const good = example()
+```
+
+Reference: [Link to documentation or resource](https://example.com)
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/mcp-builder/rules/best-practices.md

@@ -0,0 +1,157 @@
+---
+name: mcp-best-practices
+description: MCP design patterns — workflow over endpoints, concise/detailed output, actionable errors, naming conventions
+title: "MCP Best Practices"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: best, practices
+---
+
+# MCP Best Practices
+
+> Design for workflows, not endpoints. Optimize for agent context.
+
+---
+
+## Core Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Workflows > Endpoints** | `schedule_event` vs separate `check` + `create` |
+| **Context-Aware** | Offer `concise` vs `detailed` formats |
+| **Actionable Errors** | "Try filter='active'" not "Invalid filter" |
+| **Natural Grouping** | Consistent prefixes for discoverability |
+
+---
+
+## Tool Design
+
+### Input Schema
+
+```python
+# Use descriptive Field descriptions
+query: str = Field(description="Search terms (supports AND/OR)")
+limit: int = Field(default=10, ge=1, le=100)
+format: str = Field(default="concise", pattern="^(concise|detailed)$")
+```
+
+### Tool Annotations
+
+```python
+@mcp.tool(
+    readOnlyHint=True,      # Read-only operation
+    destructiveHint=False,  # Non-destructive
+    idempotentHint=True,    # Same result on retry
+    openWorldHint=True,     # External interaction
+)
+```
+
+---
+
+## Response Format
+
+### Concise vs Detailed
+
+```python
+if format == "concise":
+    return json.dumps({
+        "id": item.id,
+        "title": item.title,
+        "status": item.status
+    })
+else:
+    return json.dumps(item.dict())  # Full object
+```
+
+### Markdown for Readability
+
+```python
+# For complex data, Markdown is more readable
+return f"""
+## {item.title}
+
+**Status:** {item.status}
+**Created:** {item.created_at}
+
+### Description
+{item.description}
+"""
+```
+
+---
+
+## Error Handling
+
+```python
+# ❌ Bad
+raise Exception("Invalid filter")
+
+# ✅ Good
+raise Exception(
+    "Invalid filter value. "
+    "Valid options: 'active', 'archived', 'all'. "
+    "Try: filter='active' to see current items."
+)
+```
+
+---
+
+## Pagination
+
+```python
+async def list_items(page: int = 1, per_page: int = 20) -> str:
+    """
+    Args:
+        page: Page number (1-indexed)
+        per_page: Items per page (max 100)
+
+    Returns:
+        JSON with items array and pagination metadata
+    """
+    items = await api.get_items(page=page, per_page=per_page)
+    
+    return json.dumps({
+        "items": items,
+        "pagination": {
+            "page": page,
+            "per_page": per_page,
+            "total": total_count,
+            "has_more": page * per_page < total_count
+        }
+    })
+```
+
+---
+
+## Naming Conventions
+
+| Pattern | Example |
+|---------|---------|
+| Resource prefix | `user_get`, `user_create`, `user_list` |
+| Action-first | `search_users`, `create_task`, `delete_file` |
+| Consistent verbs | `get`, `list`, `create`, `update`, `delete` |
+
+---
+
+## Security
+
+- Never expose credentials in responses
+- Validate all inputs
+- Rate limit where appropriate
+- Log operations for audit
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [../SKILL.md](../SKILL.md) | Phase 3 review checklist |
+| [design-principles.md](design-principles.md) | Core MCP concepts |
+| [python-implementation.md](python-implementation.md) | Python patterns |
+| [typescript-implementation.md](typescript-implementation.md) | TypeScript patterns |
+| [evaluation.md](evaluation.md) | Phase 4 testing |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/mcp-builder/rules/design-principles.md

@@ -0,0 +1,105 @@
+---
+name: mcp-design-principles
+description: Core MCP concepts — tool/resource/prompt design, transport selection, error handling, security patterns
+title: "MCP Server Design Principles"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: design, principles
+---
+
+# MCP Server Design Principles
+
+> Core principles for building MCP (Model Context Protocol) servers.
+
+---
+
+## MCP Overview
+
+Model Context Protocol - standard for connecting AI systems with external tools and data.
+
+| Concept       | Purpose                      |
+| ------------- | ---------------------------- |
+| **Tools**     | Functions AI can call        |
+| **Resources** | Data AI can read             |
+| **Prompts**   | Pre-defined prompt templates |
+
+---
+
+## Server Architecture
+
+```
+my-mcp-server/
+├── src/index.ts    # Main entry
+├── package.json
+└── tsconfig.json
+```
+
+| Transport     | Use                      |
+| ------------- | ------------------------ |
+| **Stdio**     | Local, CLI-based         |
+| **SSE**       | Web-based, streaming     |
+| **WebSocket** | Real-time, bidirectional |
+
+---
+
+## Tool Design
+
+| Principle         | Description                                |
+| ----------------- | ------------------------------------------ |
+| Clear name        | Action-oriented (get_weather, create_user) |
+| Single purpose    | One thing well                             |
+| Validated input   | Schema with types and descriptions         |
+| Structured output | Predictable response format                |
+
+---
+
+## Resource Patterns
+
+| Type     | Use                       | URI Example         |
+| -------- | ------------------------- | ------------------- |
+| Static   | Fixed data (config, docs) | `docs://readme`     |
+| Dynamic  | Generated on request      | `users://{userId}`  |
+| Template | URI with parameters       | `files://project/*` |
+
+---
+
+## Error Handling
+
+| Situation      | Response                   |
+| -------------- | -------------------------- |
+| Invalid params | Validation error message   |
+| Not found      | Clear "not found"          |
+| Server error   | Generic error, log details |
+
+---
+
+## Security & Config
+
+- Validate all tool inputs, sanitize user data
+- Use environment variables for API keys
+- Don't log secrets, validate permissions
+
+---
+
+## Best Practices Checklist
+
+- [ ] Clear, action-oriented tool names
+- [ ] Complete input schemas with descriptions
+- [ ] Structured JSON output
+- [ ] Error handling for all cases
+- [ ] Environment-based configuration
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [../SKILL.md](../SKILL.md) | 4-phase build, framework selection |
+| [quickstart.md](quickstart.md) | Setup guides (Python/TypeScript) |
+| [best-practices.md](best-practices.md) | Workflow design, error patterns |
+| [engineering-spec.md](engineering-spec.md) | Full engineering spec |
+
+---
+
+⚡ PikaKit v3.9.134