@amrhas82/agentic-kit 1.5.0 → 1.7.5

package/packages/opencode/command/mcp-builder.md

@@ -1,282 +0,0 @@
----
-description: Create high-quality MCP servers that enable LLMs to interact with external services through well-designed tools
-argument-hint: <service-to-integrate> <language-choice>
----
-
-Build high-quality MCP (Model Context Protocol) servers that enable LLMs to effectively interact with external services and APIs.
-
-## MCP Development Workflow
-
-### Phase 1: Research and Planning
-
-#### 1.1 Agent-Centric Design Principles
-
-**Build for Workflows, Not Just API Endpoints:**
-- Don't simply wrap existing API endpoints - build thoughtful, high-impact workflow tools
-- Consolidate related operations (e.g., `schedule_event` that checks availability AND creates event)
-- Focus on tools that enable complete tasks, not just individual API calls
-- Consider what workflows agents actually need to accomplish
-
-**Optimize for Limited Context:**
-- Agents have constrained context windows - make every token count
-- Return high-signal information, not exhaustive data dumps
-- Provide "concise" vs "detailed" response format options
-- Default to human-readable identifiers over technical codes (names over IDs)
-- Consider the agent's context budget as a scarce resource
-
-**Design Actionable Error Messages:**
-- Error messages should guide agents toward correct usage patterns
-- Suggest specific next steps: "Try using filter='active_only' to reduce results"
-- Make errors educational, not just diagnostic
-- Help agents learn proper tool usage through clear feedback
-
-**Follow Natural Task Subdivisions:**
-- Tool names should reflect how humans think about tasks
-- Group related tools with consistent prefixes for discoverability
-- Design tools around natural workflows, not just API structure
-
-#### 1.2 Study MCP Protocol
-Fetch the latest MCP protocol documentation:
-```bash
-# Load comprehensive MCP specification
-https://modelcontextprotocol.io/llms-full.txt
-```
-
-#### 1.3 Framework Documentation
-
-**Python Implementation:**
-- Load: `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
-- Use FastMCP framework for Python servers
-
-**Node/TypeScript Implementation:**
-- Load: `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
-- Use MCP SDK for Node/TypeScript servers
-
-#### 1.4 API Documentation Study
-Exhaustively study the service API:
-- Official API reference documentation
-- Authentication and authorization requirements
-- Rate limiting and pagination patterns
-- Error responses and status codes
-- Available endpoints and their parameters
-- Data models and schemas
-
-#### 1.5 Implementation Planning
-Create a comprehensive plan:
-
-**Tool Selection:**
-- List the most valuable endpoints/operations to implement
-- Prioritize tools that enable common and important use cases
-- Consider which tools work together for complex workflows
-
-**Shared Utilities:**
-- Identify common API request patterns
-- Design authentication handling
-- Create pagination helpers
-- Build error handling utilities
-
-### Phase 2: Development
-
-#### 2.1 Project Setup
-```bash
-# Python setup
-pip install fastmcp
-mkdir mcp-server
-cd mcp-server
-
-# Node/TypeScript setup
-npm init -y
-npm install @modelcontextprotocol/sdk
-mkdir mcp-server
-cd mcp-server
-```
-
-#### 2.2 Tool Design Patterns
-
-**Workflow-Focused Tools:**
-```python
-# ❌ BAD: Simple API wrapper
-@tool
-def get_user(user_id: str) -> dict:
-    return api.get(f"/users/{user_id}")
-
-# ✅ GOOD: Complete workflow tool
-@tool
-def get_user_profile(user_id: str, include_recent_activity: bool = False) -> dict:
-    """
-    Get comprehensive user profile information.
-    
-    Args:
-        user_id: User identifier
-        include_recent_activity: Include last 30 days of activity
-        
-    Returns:
-        Complete user profile with optional activity data
-    """
-    user = api.get(f"/users/{user_id}")
-    if include_recent_activity:
-        activity = api.get(f"/users/{user_id}/activity", params={"days": 30})
-        user["recent_activity"] = activity
-    
-    return user
-```
-
-**Context-Aware Responses:**
-```python
-@tool
-def search_items(query: str, max_results: int = 10) -> dict:
-    """
-    Search for items with intelligent result formatting.
-    
-    Args:
-        query: Search query
-        max_results: Maximum number of results (default: 10, max: 50)
-        
-    Returns:
-        Concise search results with key identifiers and summaries
-    """
-    results = api.get("/search", params={"q": query, "limit": max_results})
-    
-    # Return concise, actionable format
-    return {
-        "query": query,
-        "total_found": len(results),
-        "items": [
-            {
-                "id": item["id"],
-                "name": item["name"], 
-                "summary": item["description"][:100] + "...",
-                "relevance_score": item["score"]
-            }
-            for item in results
-        ]
-    }
-```
-
-#### 2.3 Error Handling
-```python
-@tool
-def create_event(event_data: dict) -> dict:
-    """
-    Create a calendar event with validation.
-    
-    Args:
-        event_data: Event details including title, start, end, attendees
-        
-    Returns:
-        Created event information
-        
-    Raises:
-        ValidationError: If event data is invalid (missing required fields, 
-                        scheduling conflicts, or invalid time format)
-    """
-    try:
-        # Validate event data
-        if not event_data.get("title"):
-            raise ValueError("Event title is required")
-            
-        # Check for conflicts
-        conflicts = check_schedule_conflicts(event_data)
-        if conflicts:
-            return {
-                "success": False,
-                "error": "Schedule conflict detected",
-                "conflicting_events": conflicts,
-                "suggestion": "Try adjusting the time or use check_availability tool first"
-            }
-            
-        # Create event
-        result = api.post("/events", json=event_data)
-        return {"success": True, "event": result}
-        
-    except ValidationError as e:
-        return {
-            "success": False, 
-            "error": str(e),
-            "suggestion": "Ensure all required fields are provided and times are in ISO format"
-        }
-```
-
-### Phase 3: Testing and Evaluation
-
-#### 3.1 Create Evaluation Scenarios
-```python
-# Test realistic agent workflows
-test_scenarios = [
-    {
-        "name": "Complete user onboarding workflow",
-        "steps": [
-            "create_user",
-            "send_welcome_email", 
-            "schedule_kickoff_call",
-            "add_to_team"
-        ]
-    },
-    {
-        "name": "Project management workflow",
-        "steps": [
-            "create_project",
-            "add_team_members",
-            "create_tasks", 
-            "set_milestones",
-            "generate_report"
-        ]
-    }
-]
-```
-
-#### 3.2 Agent Testing
-Test the MCP server with real LLM agents:
-- Verify tools work for actual use cases
-- Check error messages guide correct usage
-- Ensure responses are appropriate for agent context
-- Validate workflow completeness
-
-### Phase 4: Documentation and Deployment
-
-#### 4.1 Tool Documentation
-Each tool should include:
-- Clear description of purpose and use cases
-- Parameter documentation with types and descriptions
-- Return value documentation
-- Usage examples
-- Error handling guidance
-
-#### 4.2 Best Practices Checklist
-
-**Tool Design:**
-- [ ] Tools enable complete workflows, not just API calls
-- [ ] Error messages are actionable and educational
-- [ ] Responses are concise but informative
-- [ ] Tool names reflect natural task subdivisions
-- [ ] Related tools have consistent prefixes
-
-**Development:**
-- [ ] Comprehensive API coverage studied
-- [ ] Authentication handled securely
-- [ ] Rate limiting respected
-- [ ] Pagination implemented
-- [ ] Error handling robust
-- [ ] Type safety maintained
-
-**Testing:**
-- [ ] Realistic evaluation scenarios created
-- [ ] Agent feedback incorporated
-- [ ] Performance tested
-- [ ] Edge cases covered
-
-## Usage Examples
-
-**Create MCP server for calendar service:**
-`/mcp-builder "Google Calendar API" "python"`
-
-**Build integration for project management:**
-`/mcp-builder "Jira API" "typescript"`
-
-**Develop customer support tools:**
-`/mcp-builder "Zendesk API" "python"`
-
-**Create data analytics server:**
-`/mcp-builder "Analytics API" "typescript"`
-
-Remember: Quality MCP servers enable LLMs to accomplish real-world tasks effectively through well-designed, workflow-focused tools.

package/packages/opencode/command/pdf/scripts/check_bounding_boxes.py

@@ -1,70 +0,0 @@
-from dataclasses import dataclass
-import json
-import sys
-
-
-# Script to check that the `fields.json` file that Claude creates when analyzing PDFs
-# does not have overlapping bounding boxes. See forms.md.
-
-
-@dataclass
-class RectAndField:
-    rect: list[float]
-    rect_type: str
-    field: dict
-
-
-# Returns a list of messages that are printed to stdout for Claude to read.
-def get_bounding_box_messages(fields_json_stream) -> list[str]:
-    messages = []
-    fields = json.load(fields_json_stream)
-    messages.append(f"Read {len(fields['form_fields'])} fields")
-
-    def rects_intersect(r1, r2):
-        disjoint_horizontal = r1[0] >= r2[2] or r1[2] <= r2[0]
-        disjoint_vertical = r1[1] >= r2[3] or r1[3] <= r2[1]
-        return not (disjoint_horizontal or disjoint_vertical)
-
-    rects_and_fields = []
-    for f in fields["form_fields"]:
-        rects_and_fields.append(RectAndField(f["label_bounding_box"], "label", f))
-        rects_and_fields.append(RectAndField(f["entry_bounding_box"], "entry", f))
-
-    has_error = False
-    for i, ri in enumerate(rects_and_fields):
-        # This is O(N^2); we can optimize if it becomes a problem.
-        for j in range(i + 1, len(rects_and_fields)):
-            rj = rects_and_fields[j]
-            if ri.field["page_number"] == rj.field["page_number"] and rects_intersect(ri.rect, rj.rect):
-                has_error = True
-                if ri.field is rj.field:
-                    messages.append(f"FAILURE: intersection between label and entry bounding boxes for `{ri.field['description']}` ({ri.rect}, {rj.rect})")
-                else:
-                    messages.append(f"FAILURE: intersection between {ri.rect_type} bounding box for `{ri.field['description']}` ({ri.rect}) and {rj.rect_type} bounding box for `{rj.field['description']}` ({rj.rect})")
-                if len(messages) >= 20:
-                    messages.append("Aborting further checks; fix bounding boxes and try again")
-                    return messages
-        if ri.rect_type == "entry":
-            if "entry_text" in ri.field:
-                font_size = ri.field["entry_text"].get("font_size", 14)
-                entry_height = ri.rect[3] - ri.rect[1]
-                if entry_height < font_size:
-                    has_error = True
-                    messages.append(f"FAILURE: entry bounding box height ({entry_height}) for `{ri.field['description']}` is too short for the text content (font size: {font_size}). Increase the box height or decrease the font size.")
-                    if len(messages) >= 20:
-                        messages.append("Aborting further checks; fix bounding boxes and try again")
-                        return messages
-
-    if not has_error:
-        messages.append("SUCCESS: All bounding boxes are valid")
-    return messages
-
-if __name__ == "__main__":
-    if len(sys.argv) != 2:
-        print("Usage: check_bounding_boxes.py [fields.json]")
-        sys.exit(1)
-    # Input file should be in the `fields.json` format described in forms.md.
-    with open(sys.argv[1]) as f:
-        messages = get_bounding_box_messages(f)
-    for msg in messages:
-        print(msg)

package/packages/opencode/command/pdf/scripts/check_bounding_boxes_test.py

@@ -1,226 +0,0 @@
-import unittest
-import json
-import io
-from check_bounding_boxes import get_bounding_box_messages
-
-
-# Currently this is not run automatically in CI; it's just for documentation and manual checking.
-class TestGetBoundingBoxMessages(unittest.TestCase):
-    
-    def create_json_stream(self, data):
-        """Helper to create a JSON stream from data"""
-        return io.StringIO(json.dumps(data))
-    
-    def test_no_intersections(self):
-        """Test case with no bounding box intersections"""
-        data = {
-            "form_fields": [
-                {
-                    "description": "Name",
-                    "page_number": 1,
-                    "label_bounding_box": [10, 10, 50, 30],
-                    "entry_bounding_box": [60, 10, 150, 30]
-                },
-                {
-                    "description": "Email",
-                    "page_number": 1,
-                    "label_bounding_box": [10, 40, 50, 60],
-                    "entry_bounding_box": [60, 40, 150, 60]
-                }
-            ]
-        }
-        
-        stream = self.create_json_stream(data)
-        messages = get_bounding_box_messages(stream)
-        self.assertTrue(any("SUCCESS" in msg for msg in messages))
-        self.assertFalse(any("FAILURE" in msg for msg in messages))
-    
-    def test_label_entry_intersection_same_field(self):
-        """Test intersection between label and entry of the same field"""
-        data = {
-            "form_fields": [
-                {
-                    "description": "Name",
-                    "page_number": 1,
-                    "label_bounding_box": [10, 10, 60, 30],
-                    "entry_bounding_box": [50, 10, 150, 30]  # Overlaps with label
-                }
-            ]
-        }
-        
-        stream = self.create_json_stream(data)
-        messages = get_bounding_box_messages(stream)
-        self.assertTrue(any("FAILURE" in msg and "intersection" in msg for msg in messages))
-        self.assertFalse(any("SUCCESS" in msg for msg in messages))
-    
-    def test_intersection_between_different_fields(self):
-        """Test intersection between bounding boxes of different fields"""
-        data = {
-            "form_fields": [
-                {
-                    "description": "Name",
-                    "page_number": 1,
-                    "label_bounding_box": [10, 10, 50, 30],
-                    "entry_bounding_box": [60, 10, 150, 30]
-                },
-                {
-                    "description": "Email",
-                    "page_number": 1,
-                    "label_bounding_box": [40, 20, 80, 40],  # Overlaps with Name's boxes
-                    "entry_bounding_box": [160, 10, 250, 30]
-                }
-            ]
-        }
-        
-        stream = self.create_json_stream(data)
-        messages = get_bounding_box_messages(stream)
-        self.assertTrue(any("FAILURE" in msg and "intersection" in msg for msg in messages))
-        self.assertFalse(any("SUCCESS" in msg for msg in messages))
-    
-    def test_different_pages_no_intersection(self):
-        """Test that boxes on different pages don't count as intersecting"""
-        data = {
-            "form_fields": [
-                {
-                    "description": "Name",
-                    "page_number": 1,
-                    "label_bounding_box": [10, 10, 50, 30],
-                    "entry_bounding_box": [60, 10, 150, 30]
-                },
-                {
-                    "description": "Email",
-                    "page_number": 2,
-                    "label_bounding_box": [10, 10, 50, 30],  # Same coordinates but different page
-                    "entry_bounding_box": [60, 10, 150, 30]
-                }
-            ]
-        }
-        
-        stream = self.create_json_stream(data)
-        messages = get_bounding_box_messages(stream)
-        self.assertTrue(any("SUCCESS" in msg for msg in messages))
-        self.assertFalse(any("FAILURE" in msg for msg in messages))
-    
-    def test_entry_height_too_small(self):
-        """Test that entry box height is checked against font size"""
-        data = {
-            "form_fields": [
-                {
-                    "description": "Name",
-                    "page_number": 1,
-                    "label_bounding_box": [10, 10, 50, 30],
-                    "entry_bounding_box": [60, 10, 150, 20],  # Height is 10
-                    "entry_text": {
-                        "font_size": 14  # Font size larger than height
-                    }
-                }
-            ]
-        }
-        
-        stream = self.create_json_stream(data)
-        messages = get_bounding_box_messages(stream)
-        self.assertTrue(any("FAILURE" in msg and "height" in msg for msg in messages))
-        self.assertFalse(any("SUCCESS" in msg for msg in messages))
-    
-    def test_entry_height_adequate(self):
-        """Test that adequate entry box height passes"""
-        data = {
-            "form_fields": [
-                {
-                    "description": "Name",
-                    "page_number": 1,
-                    "label_bounding_box": [10, 10, 50, 30],
-                    "entry_bounding_box": [60, 10, 150, 30],  # Height is 20
-                    "entry_text": {
-                        "font_size": 14  # Font size smaller than height
-                    }
-                }
-            ]
-        }
-        
-        stream = self.create_json_stream(data)
-        messages = get_bounding_box_messages(stream)
-        self.assertTrue(any("SUCCESS" in msg for msg in messages))
-        self.assertFalse(any("FAILURE" in msg for msg in messages))
-    
-    def test_default_font_size(self):
-        """Test that default font size is used when not specified"""
-        data = {
-            "form_fields": [
-                {
-                    "description": "Name",
-                    "page_number": 1,
-                    "label_bounding_box": [10, 10, 50, 30],
-                    "entry_bounding_box": [60, 10, 150, 20],  # Height is 10
-                    "entry_text": {}  # No font_size specified, should use default 14
-                }
-            ]
-        }
-        
-        stream = self.create_json_stream(data)
-        messages = get_bounding_box_messages(stream)
-        self.assertTrue(any("FAILURE" in msg and "height" in msg for msg in messages))
-        self.assertFalse(any("SUCCESS" in msg for msg in messages))
-    
-    def test_no_entry_text(self):
-        """Test that missing entry_text doesn't cause height check"""
-        data = {
-            "form_fields": [
-                {
-                    "description": "Name",
-                    "page_number": 1,
-                    "label_bounding_box": [10, 10, 50, 30],
-                    "entry_bounding_box": [60, 10, 150, 20]  # Small height but no entry_text
-                }
-            ]
-        }
-        
-        stream = self.create_json_stream(data)
-        messages = get_bounding_box_messages(stream)
-        self.assertTrue(any("SUCCESS" in msg for msg in messages))
-        self.assertFalse(any("FAILURE" in msg for msg in messages))
-    
-    def test_multiple_errors_limit(self):
-        """Test that error messages are limited to prevent excessive output"""
-        fields = []
-        # Create many overlapping fields
-        for i in range(25):
-            fields.append({
-                "description": f"Field{i}",
-                "page_number": 1,
-                "label_bounding_box": [10, 10, 50, 30],  # All overlap
-                "entry_bounding_box": [20, 15, 60, 35]   # All overlap
-            })
-        
-        data = {"form_fields": fields}
-        
-        stream = self.create_json_stream(data)
-        messages = get_bounding_box_messages(stream)
-        # Should abort after ~20 messages
-        self.assertTrue(any("Aborting" in msg for msg in messages))
-        # Should have some FAILURE messages but not hundreds
-        failure_count = sum(1 for msg in messages if "FAILURE" in msg)
-        self.assertGreater(failure_count, 0)
-        self.assertLess(len(messages), 30)  # Should be limited
-    
-    def test_edge_touching_boxes(self):
-        """Test that boxes touching at edges don't count as intersecting"""
-        data = {
-            "form_fields": [
-                {
-                    "description": "Name",
-                    "page_number": 1,
-                    "label_bounding_box": [10, 10, 50, 30],
-                    "entry_bounding_box": [50, 10, 150, 30]  # Touches at x=50
-                }
-            ]
-        }
-        
-        stream = self.create_json_stream(data)
-        messages = get_bounding_box_messages(stream)
-        self.assertTrue(any("SUCCESS" in msg for msg in messages))
-        self.assertFalse(any("FAILURE" in msg for msg in messages))
-    
-
-if __name__ == '__main__':
-    unittest.main()

package/packages/opencode/command/pdf/scripts/check_fillable_fields.py

@@ -1,12 +0,0 @@
-import sys
-from pypdf import PdfReader
-
-
-# Script for Claude to run to determine whether a PDF has fillable form fields. See forms.md.
-
-
-reader = PdfReader(sys.argv[1])
-if (reader.get_fields()):
-    print("This PDF has fillable form fields")
-else:
-    print("This PDF does not have fillable form fields; you will need to visually determine where to enter data")

package/packages/opencode/command/pdf/scripts/convert_pdf_to_images.py

@@ -1,35 +0,0 @@
-import os
-import sys
-
-from pdf2image import convert_from_path
-
-
-# Converts each page of a PDF to a PNG image.
-
-
-def convert(pdf_path, output_dir, max_dim=1000):
-    images = convert_from_path(pdf_path, dpi=200)
-
-    for i, image in enumerate(images):
-        # Scale image if needed to keep width/height under `max_dim`
-        width, height = image.size
-        if width > max_dim or height > max_dim:
-            scale_factor = min(max_dim / width, max_dim / height)
-            new_width = int(width * scale_factor)
-            new_height = int(height * scale_factor)
-            image = image.resize((new_width, new_height))
-        
-        image_path = os.path.join(output_dir, f"page_{i+1}.png")
-        image.save(image_path)
-        print(f"Saved page {i+1} as {image_path} (size: {image.size})")
-
-    print(f"Converted {len(images)} pages to PNG images")
-
-
-if __name__ == "__main__":
-    if len(sys.argv) != 3:
-        print("Usage: convert_pdf_to_images.py [input pdf] [output directory]")
-        sys.exit(1)
-    pdf_path = sys.argv[1]
-    output_directory = sys.argv[2]
-    convert(pdf_path, output_directory)

package/packages/opencode/command/pdf/scripts/create_validation_image.py

@@ -1,41 +0,0 @@
-import json
-import sys
-
-from PIL import Image, ImageDraw
-
-
-# Creates "validation" images with rectangles for the bounding box information that
-# Claude creates when determining where to add text annotations in PDFs. See forms.md.
-
-
-def create_validation_image(page_number, fields_json_path, input_path, output_path):
-    # Input file should be in the `fields.json` format described in forms.md.
-    with open(fields_json_path, 'r') as f:
-        data = json.load(f)
-
-        img = Image.open(input_path)
-        draw = ImageDraw.Draw(img)
-        num_boxes = 0
-        
-        for field in data["form_fields"]:
-            if field["page_number"] == page_number:
-                entry_box = field['entry_bounding_box']
-                label_box = field['label_bounding_box']
-                # Draw red rectangle over entry bounding box and blue rectangle over the label.
-                draw.rectangle(entry_box, outline='red', width=2)
-                draw.rectangle(label_box, outline='blue', width=2)
-                num_boxes += 2
-        
-        img.save(output_path)
-        print(f"Created validation image at {output_path} with {num_boxes} bounding boxes")
-
-
-if __name__ == "__main__":
-    if len(sys.argv) != 5:
-        print("Usage: create_validation_image.py [page number] [fields.json file] [input image path] [output image path]")
-        sys.exit(1)
-    page_number = int(sys.argv[1])
-    fields_json_path = sys.argv[2]
-    input_image_path = sys.argv[3]
-    output_image_path = sys.argv[4]
-    create_validation_image(page_number, fields_json_path, input_image_path, output_image_path)