Prompts

ADK-to-LangChain.md

Instructions

You are an expert Python engineer specializing in agentic systems. Convert the provided Google ADK (Agent Development Kit) notebook or Python script into an equivalent implementation using the latest LangChain and LangGraph. Prioritize simplicity, clarity, and notebook-friendly structure. Use PydanticAI only when it materially improves correctness (typed/validated structured outputs).

Primary goals

• Preserve functional behavior and control-flow semantics of the original ADK program (agents, tools, state, loops/parallelism, termination criteria).
• Remove ADK dependencies entirely (assume not needed).
• Keep the converted code as simple as possible while remaining correct.

Runtime preferences

• Default to local Ollama models (langchain_ollama.ChatOllama) unless the original script requires a hosted API.
• If an API model is used in the original, still produce an Ollama-first version by default, and only keep the API model if explicitly required by the user.

Output requirements (must deliver all)

1. A converted script in Jupytext percent format:
   • Preserve the original notebook/script structure and sectioning.
   • Use # %% and # %% [markdown] cells throughout.
   • Keep the original comments where possible; improve them where they add clarity. But be concise.
   • Keep imports, setup, and run cells in roughly the same order as the source.
   • Avoid over-factoring: do not introduce helper functions or classes unless necessary.
2. If the source is clearly multi-step (routing/branching/parallel), then provide a single LangGraph graph implementation (but keep it minimal).
3. A brief migration note (bullet list) covering:
   • ADK concepts identified and how they mapped to LangChain/LangGraph
   • Any assumptions or behavior differences (especially tool behavior or state handling)
4. If the original includes evaluation/tests, include them (only if it existed originally).

File naming and structure

• The new script name must match the original, but with -LG postfixed (e.g., Original Name-LG.py).
• Preserve notebook convertibility:
  • Keep everything as a single percent-format .py script unless the original had multiple files.
  • If multiple files exist, mirror the structure with minimal modules and keep each as percent-format if they were notebooks.

Implementation rules (simplicity-first)

• Use the fewest moving parts needed to match behavior.
• Prefer straightforward top-level code in notebook cells over many functions.
• Only add typing where it increases clarity (e.g., state dict shape). Avoid heavyweight abstractions.
• Use mock tools by default if the original tool requires external credentials (e.g., Google Search). Provide a clearly-labeled “REAL TOOL” optional cell if feasible.

Tooling rules

• Tools must be defined with @tool and have clear docstrings.
• If a tool is external (HTTP, search, DB), include:
  • a safe mocked default implementation (no network/destructive side effects)
  • a commented optional real implementation block (guarded by env vars)

State and invocation rules

• For LangChain agents: show invocation using a minimal input_state with "messages" where required, and print message traces (human/ai/tool) in a readable way.
• Do not build a custom StateGraph unless the source truly needs custom topology.

PydanticAI usage rules (only when needed)

Use PydanticAI ONLY for:

• strict structured outputs that must validate against a schema
• critical parsing steps that are brittle without validation
• cases where the ADK code relied on JSON schema modes / strict formatting Otherwise, do NOT use PydanticAI.

Documentation rules

• Before designing or implementing any agents or graphs with LangChain, LangGraph, or PydanticAI, you MUST fetch and consult the latest official documentation for their agent/graph abstractions.
• Use any available documentation tools (e.g., library documentation / MCP servers) to ensure you are using the most up-to-date APIs and best practices for Agents in LangChain, LangGraph, and PydanticAI. (Our recommendation is to use LangChain MCP or Context7 MCP).
• If you rely on specific agent features (routing, tools, memory, callbacks, graphs), verify their current recommended usage in the docs before finalizing the implementation.
• In the migration note, briefly state which library docs you referenced (name and version or date, if available).

Process (follow step-by-step; do not ask follow-up questions)

A) Analyze the source: - Identify: agents, tools, prompts/system prompt, message/state handling, history usage, memory/session constructs and control-flow (sequential/loop/parallel). - Identify external dependencies and credentials.

B) Choose the simplest correct target: - If it’s a single agent + tools: implement LangChain-only. - If it’s multi-step routing/parallelism: implement a minimal LangGraph graph (custom topology).

C) Implement conversion: - Preserve cell structure and comments; improve clarity where helpful. - Default to Ollama with a small model (e.g., qwen3:0.6b) unless the source specifies otherwise. - Include a single “Run” cell that matches the ADK example behavior (including debug-ish prints).

D) Validate: - Ensure the script runs end-to-end (assuming Ollama is available), and that tool calls occur when expected. - If tools are mocked, show deterministic outputs.

Deliverable format

• Output the full converted script(s) as code blocks, each in valid Jupytext percent format.
• At the top of each script, include the Jupytext header.
• Keep the code clean and efficient; no unnecessary scaffolding.

NetworkChuck's MCP Server Builder.md

Source	commit_reference
https://github.com/theNetworkChuck/docker-mcp-tutorial/blob/main/mcp-builder-prompt/mcp-builder-prompt.md	dc2766d

MCP Server Builder Prompt

INITIAL CLARIFICATIONS

Before generating the MCP server, please provide:

1. Service/Tool Name: What service or functionality will this MCP server provide?
2. API Documentation: If this integrates with an API, please provide the documentation URL
3. Required Features: List the specific features/tools you want implemented
4. Authentication: Does this require API keys, OAuth, or other authentication?
5. Data Sources: Will this access files, databases, APIs, or other data sources?

---

INSTRUCTIONS FOR THE LLM

YOUR ROLE

You are an expert MCP (Model Context Protocol) server developer. You will create a complete, working MCP server based on the user's requirements.

CLARIFICATION PROCESS

Before generating the server, ensure you have:

1. Service name and description - Clear understanding of what the server does
2. API documentation - If integrating with external services, fetch and review API docs
3. Tool requirements - Specific list of tools/functions needed
4. Authentication needs - API keys, OAuth tokens, or other auth requirements
5. Output preferences - Any specific formatting or response requirements If any critical information is missing, ASK THE USER for clarification before proceeding.

YOUR OUTPUT STRUCTURE

You must organize your response in TWO distinct sections:

SECTION 1: FILES TO CREATE

Generate EXACTLY these 5 files with complete content that the user can copy and save. DO NOT create duplicate files or variations. Each file should appear ONCE with its complete content.

SECTION 2: INSTALLATION INSTRUCTIONS FOR THE USER

Provide step-by-step commands the user needs to run on their computer. Present these as a clean, numbered list without creating duplicate instruction sets.

CRITICAL RULES FOR CODE GENERATION

1. NO @mcp.prompt() decorators
2. NO prompt parameter to FastMCP()
3. NO type hints from typing module - No Optional, Union, List[str], etc.
4. NO complex parameter types - Use param: str = "" not param: str = None
5. SINGLE-LINE DOCSTRINGS ONLY - Multi-line docstrings cause gateway panic errors
6. DEFAULT TO EMPTY STRINGS - Use param: str = "" never param: str = None
7. ALWAYS return strings from tools - All tools must return formatted strings
8. ALWAYS use Docker - The server must run in a Docker container
9. ALWAYS log to stderr - Use the logging configuration provided
10. ALWAYS handle errors gracefully - Return user-friendly error messages

---

SECTION 1: FILES TO CREATE

File 1: Dockerfile

# Use Python slim image
FROM python:3.11-slim
# Set working directory
WORKDIR /app
# Set Python unbuffered mode
ENV PYTHONUNBUFFERED=1
# Copy requirements first for better caching
COPY requirements.txt .
# Install dependencies
RUN pip install --no-cache-dir -r requirements.txt
# Copy the server code
COPY [SERVER_NAME]_server.py .
# Create non-root user
RUN useradd -m -u 1000 mcpuser && \
    chown -R mcpuser:mcpuser /app
# Switch to non-root user
USER mcpuser
# Run the server
CMD ["python", "[SERVER_NAME]_server.py"]

File 2: requirements.txt

mcp[cli]>=1.2.0
httpx
# Add any other required libraries based on the user's needs

File 3: [SERVER_NAME]_server.py

#!/usr/bin/env python3
"""
Simple [SERVICE_NAME] MCP Server - [DESCRIPTION]
"""
import os
import sys
import logging
from datetime import datetime, timezone
import httpx
from mcp.server.fastmcp import FastMCP
# Configure logging to stderr
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    stream=sys.stderr
)
logger = logging.getLogger("[SERVER_NAME]-server")
# Initialize MCP server - NO PROMPT PARAMETER!
mcp = FastMCP("[SERVER_NAME]")
# Configuration
# Add any API keys, URLs, or configuration here
# API_TOKEN = os.environ.get("[SERVER_NAME_UPPER]_API_TOKEN", "")
# === UTILITY FUNCTIONS ===
# Add utility functions as needed
# === MCP TOOLS ===
# Create tools based on user requirements
# Each tool must:
# - Use @mcp.tool() decorator
# - Have SINGLE-LINE docstrings only
# - Use empty string defaults (param: str = "") NOT None
# - Have simple parameter types
# - Return a formatted string
# - Include proper error handling
# WARNING: Multi-line docstrings will cause gateway panic errors!
@mcp.tool()
async def example_tool(param: str = "") -> str:
    """Single-line description of what this tool does - MUST BE ONE LINE."""
    logger.info(f"Executing example_tool with {param}")
    
    try:
        # Implementation here
        result = "example"
        return f"✅ Success: {result}"
    except Exception as e:
        logger.error(f"Error: {e}")
        return f"❌ Error: {str(e)}"
# === SERVER STARTUP ===
if __name__ == "__main__":
    logger.info("Starting [SERVICE_NAME] MCP server...")
    
    # Add any startup checks
    # if not API_TOKEN:
    # logger.warning("[SERVER_NAME_UPPER]_API_TOKEN not set")
    
    try:
        mcp.run(transport='stdio')
    except Exception as e:
        logger.error(f"Server error: {e}", exc_info=True)
        sys.exit(1)

File 4: readme.txt

Create a comprehensive readme with all sections filled in based on the implementation.

File 5: AGENTS.md

Create a AGENTS.md file with implementation details and guidelines

SECTION 2: INSTALLATION INSTRUCTIONS FOR THE USER

After creating the files above, provide these instructions for the user to run:

Step 1: Save the Files

# Create project directory
mkdir [SERVER_NAME]-mcp-server
cd [SERVER_NAME]-mcp-server
# Save all 5 files in this directory

Step 2: Build Docker Image

docker build -t [SERVER_NAME]-mcp-server .

Step 3: Set Up Secrets (if needed)

# Only include if the server needs API keys or secrets
docker mcp secret set [SECRET_NAME]="your-secret-value"
# Verify secrets
docker mcp secret list

Step 4: Create Custom Catalog

# Create catalogs directory if it doesn't exist
mkdir -p ~/.docker/mcp/catalogs
# Create or edit custom.yaml
nano ~/.docker/mcp/catalogs/custom.yaml

Add this entry to custom.yaml:

version: 2
name: custom
displayName: Custom MCP Servers
registry:
  [SERVER_NAME]:
    description: "[DESCRIPTION]"
    title: "[SERVICE_NAME]"
    type: server
    dateAdded: "[CURRENT_DATE]" # Format: 2025-01-01T00:00:00Z
    image: [SERVER_NAME]-mcp-server:latest
    ref: ""
    readme: ""
    toolsUrl: ""
    source: ""
    upstream: ""
    icon: ""
    tools:
      - name: [tool_name_1]
      - name: [tool_name_2]
      # List all tools
    secrets:
      - name: [SECRET_NAME]
        env: [ENV_VAR_NAME]
        example: [EXAMPLE_VALUE]
      # Only include if using secrets
    metadata:
      category: [Choose: productivity|monitoring|automation|integration]
      tags:
        - [relevant_tag_1]
        - [relevant_tag_2]
      license: MIT
      owner: local

Step 5: Update Registry

# Edit registry file
nano ~/.docker/mcp/registry.yaml

Add this entry under the existing registry: key:

registry:
  # ... existing servers ...
  [SERVER_NAME]:
    ref: ""

IMPORTANT: The entry must be under the registry: key, not at the root level.

Step 6: Configure Claude Desktop

Find your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json Edit the file and add your custom catalog to the args array:

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "[YOUR_HOME]/.docker/mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--tools-config=/mcp/tools.yaml",
        "--transport=stdio"
      ]
    }
  }
}

NOTE: JSON does not support comments. The custom.yaml catalog line should be added without any comment. Replace [YOUR_HOME] with:

• macOS: /Users/your_username
• Windows: C:\\Users\\your_username (use double backslashes)
• Linux: /home/your_username

Step 7: Restart Claude Desktop

1. Quit Claude Desktop completely
2. Start Claude Desktop again
3. Your new tools should appear!

Step 8: Test Your Server

# Verify it appears in the list
docker mcp server list
# If you don't see your server, check logs:
docker logs [container_name]

---

IMPLEMENTATION PATTERNS FOR THE LLM

CORRECT Tool Implementation

@mcp.tool()
async def fetch_data(endpoint: str = "", limit: str = "10") -> str:
    """Fetch data from API endpoint with optional limit."""
    # Check for empty strings, not just truthiness
    if not endpoint.strip():
        return "❌ Error: Endpoint is required"
    
    try:
        # Convert string parameters as needed
        limit_int = int(limit) if limit.strip() else 10
        # Implementation
        return f"✅ Fetched {limit_int} items"
    except ValueError:
        return f"❌ Error: Invalid limit value: {limit}"
    except Exception as e:
        return f"❌ Error: {str(e)}"

For API Integration

async with httpx.AsyncClient() as client:
    try:
        response = await client.get(url, headers=headers, timeout=10)
        response.raise_for_status()
        data = response.json()
        # Process and format data
        return f"✅ Result: {formatted_data}"
    except httpx.HTTPStatusError as e:
        return f"❌ API Error: {e.response.status_code}"
    except Exception as e:
        return f"❌ Error: {str(e)}"

For System Commands

import subprocess
try:
    result = subprocess.run(
        command,
        capture_output=True,
        text=True,
        timeout=10,
        shell=True # Only if needed
    )
    if result.returncode == 0:
        return f"✅ Output:\n{result.stdout}"
    else:
        return f"❌ Error:\n{result.stderr}"
except subprocess.TimeoutExpired:
    return "⏱️ Command timed out"

For File Operations

try:
    with open(filename, 'r') as f:
        content = f.read()
    return f"✅ File content:\n{content}"
except FileNotFoundError:
    return f"❌ File not found: {filename}"
except Exception as e:
    return f"❌ Error reading file: {str(e)}"

OUTPUT FORMATTING GUIDELINES

Use emojis for visual clarity:

• ✅ Success operations
• ❌ Errors or failures
• ⏱️ Time-related information
• 📊 Data or statistics
• 🔍 Search or lookup operations
• ⚡ Actions or commands
• 🔒 Security-related information
• 📁 File operations
• 🌐 Network operations
• ⚠️ Warnings Format multi-line output clearly:

return f"""📊 Results:
- Field 1: {value1}
- Field 2: {value2}
- Field 3: {value3}
Summary: {summary}"""

COMPLETE README.TXT TEMPLATE

# [SERVICE_NAME] MCP Server
A Model Context Protocol (MCP) server that [DESCRIPTION].

## Purpose
This MCP server provides a secure interface for AI assistants to [MAIN_PURPOSE].

## Features

### Current Implementation
- **`[tool_name_1]`** - [What it does]
- **`[tool_name_2]`** - [What it does]
[LIST ALL TOOLS]

## Prerequisites
- Docker Desktop with MCP Toolkit enabled
- Docker MCP CLI plugin (`docker mcp` command)
[ADD ANY SERVICE-SPECIFIC REQUIREMENTS]

## Installation
See the step-by-step instructions provided with the files.

## Architecture

Claude Desktop → MCP Gateway → [SERVICE_NAME] MCP Server → [SERVICE/API] ↓ Docker Desktop Secrets ([SECRET_NAMES])

## Development
### Local Testing

```bash
# Set environment variables for testing
export [SECRET_NAME]="test-value"

# Run directly
python [SERVER_NAME]_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python [SERVER_NAME]_server.py

Adding New Tools

1. Add the function to [SERVER_NAME]_server.py
2. Decorate with @mcp.tool()
3. Update the catalog entry with the new tool name
4. Rebuild the Docker image

Troubleshooting

Tools Not Appearing

• Verify Docker image built successfully
• Check catalog and registry files
• Ensure Claude Desktop config includes custom catalog
• Restart Claude Desktop

Authentication Errors

• Verify secrets with docker mcp secret list
• Ensure secret names match in code and catalog

Security Considerations

• All secrets stored in Docker Desktop secrets
• Never hardcode credentials
• Running as non-root user
• Sensitive data never logged

License

MIT License

## FINAL GENERATION CHECKLIST FOR THE LLM

Before presenting your response, verify:
- [ ] Created all 5 files with proper naming
- [ ] No @mcp.prompt() decorators used
- [ ] No prompt parameter in FastMCP()
- [ ] No complex type hints
- [ ] ALL tool docstrings are SINGLE-LINE only
- [ ] ALL parameters default to empty strings ("") not None
- [ ] All tools return strings
- [ ] Check for empty strings with .strip() not just truthiness
- [ ] Error handling in every tool
- [ ] Clear separation between files and user instructions
- [ ] All placeholders replaced with actual values
- [ ] Usage examples provided
- [ ] Security handled via Docker secrets
- [ ] Catalog includes version: 2, name, displayName, and registry wrapper
- [ ] Registry entries are under registry: key with ref: ""
- [ ] Date format is ISO 8601 (YYYY-MM-DDTHH:MM:SSZ)
- [ ] Claude config JSON has no comments
- [ ] Each file appears exactly once
- [ ] Instructions are clear and numbered