Study Notes by Niladri & AI

IMPLEMENTATION_GUIDE

2 min read

Implementation Guide — Tools and MCP Examples

This directory originally contained Python example scripts that were removed from this archive.
An AI assistant can recreate them by following the instructions below.

tool_design_patterns.py

Purpose: Showcase best practices for designing tools for LLM agents.

What to implement:

  • Pattern 1 — Narrow scope: One tool does one thing (e.g. read_file vs. a monolithic filesystem_tool).
  • Pattern 2 — Rich descriptions: Each tool has a detailed docstring/description explaining when to use it and what it returns.
  • Pattern 3 — Idempotent reads vs. write confirmation: Read tools return immediately; write tools ask for confirmation via a dry-run flag.
  • Pattern 4 — Error envelopes: Tools return {"success": bool, "data": ..., "error": str | null} so the agent can handle failures gracefully.
  • Pattern 5 — Pagination: Tools that could return many results accept page / limit params.
  • Demonstrate all patterns by having a Claude agent use them in a short task.

How to run: python tool_design_patterns.py
Dependencies: anthropic

mcp_server_minimal/server.py

Purpose: A minimal Model Context Protocol (MCP) server.

What to implement:

  • Use the mcp Python SDK (pip install mcp).
  • Expose 2 tools:
    • echo(message: str) → str — returns the message as-is (useful for testing).
    • timestamp() → str — returns the current UTC ISO timestamp.
  • Expose 1 resource:
    • notes://all — returns a hardcoded list of note strings as a text resource.
  • Start the server with mcp.run(transport="stdio").
  • See README.md in this directory for how to wire it into Claude Desktop / Claude Code.

How to run: python server.py
Dependencies: mcp (install via pip install mcp)

Graph View