py-easy-mcp 0.2.0__py3-none-any.whl

easy_mcp/__init__.py

@@ -0,0 +1,28 @@
+"""
+easy-mcp: Ultra-lightweight, zero-dependency Python framework for Model Context Protocol (MCP).
+Build MCP servers for Claude in seconds.
+"""
+
+from easy_mcp.server import EasyMCP
+from easy_mcp.schema import function_to_tool_schema, function_to_prompt_arguments
+from easy_mcp.protocol import (
+    MCPError,
+    ParseError,
+    InvalidRequestError,
+    MethodNotFoundError,
+    InvalidParamsError,
+    InternalError,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "EasyMCP",
+    "function_to_tool_schema",
+    "function_to_prompt_arguments",
+    "MCPError",
+    "ParseError",
+    "InvalidRequestError",
+    "MethodNotFoundError",
+    "InvalidParamsError",
+    "InternalError",
+]

easy_mcp/cli.py

@@ -0,0 +1,128 @@
+"""
+CLI utilities for easy-mcp.
+Scaffold starter servers, generate Claude Desktop config, and test tools locally.
+"""
+
+import argparse
+import json
+import os
+import sys
+
+from easy_mcp import __version__
+
+STARTER_TEMPLATE = '''"""
+MCP Server generated with easy-mcp.
+Connects with Claude Desktop and Claude Code.
+"""
+
+from easy_mcp import EasyMCP
+
+mcp = EasyMCP(name="{name}", version="0.1.0", description="Starter MCP Server")
+
+
+@mcp.tool()
+def hello_world(name: str = "World") -> str:
+    """Say hello to someone.
+    
+    Args:
+        name: Name of the person to greet
+    """
+    return f"Hello, {{name}}! Welcome to MCP."
+
+
+@mcp.tool()
+def calculate(expression: str) -> str:
+    """Safely calculate a basic arithmetic expression.
+    
+    Args:
+        expression: Simple math expression like '2 + 2 * 10'
+    """
+    allowed_chars = set("0123456789+-*/(). ")
+    if not all(c in allowed_chars for c in expression):
+        return "Error: Only basic numbers and operators (+, -, *, /) are allowed."
+    try:
+        result = eval(expression, {{"__builtins__": None}}, {{}})
+        return f"Result: {{result}}"
+    except Exception as e:
+        return f"Error evaluating expression: {{e}}"
+
+
+if __name__ == "__main__":
+    # If run with --config, prints the Claude Desktop config JSON
+    if len(sys.argv) > 1 and sys.argv[1] == "--config":
+        mcp.print_claude_config()
+    else:
+        # Standard MCP stdio mode for Claude Desktop / Claude Code
+        mcp.run()
+'''
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    name = args.name or "my-mcp-server"
+    filename = args.output or "server.py"
+
+    if os.path.exists(filename) and not args.force:
+        print(f"Error: '{filename}' already exists. Use --force to overwrite.", file=sys.stderr)
+        return 1
+
+    content = STARTER_TEMPLATE.format(name=name)
+    with open(filename, "w", encoding="utf-8") as f:
+        f.write(content)
+
+    print(f"[easy-mcp] Created starter MCP server: {filename}")
+    print(f"\nNext steps:")
+    print(f"1. Test your server locally:")
+    print(f"   python {filename} --config")
+    print(f"2. Add this server to your Claude Desktop config (claude_desktop_config.json)!")
+    return 0
+
+
+def cmd_config(args: argparse.Namespace) -> int:
+    script_path = os.path.abspath(args.script)
+    if not os.path.isfile(script_path):
+        print(f"Error: Script '{args.script}' not found.", file=sys.stderr)
+        return 1
+
+    server_name = os.path.splitext(os.path.basename(script_path))[0]
+    cfg = {
+        "mcpServers": {
+            server_name: {
+                "command": "python",
+                "args": [script_path]
+            }
+        }
+    }
+    print(json.dumps(cfg, indent=2))
+    return 0
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="easy-mcp",
+        description="Fast, zero-dependency toolkit to build and configure MCP servers for Claude."
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="subcommand", help="Available subcommands")
+
+    # init
+    p_init = subparsers.add_parser("init", help="Scaffold a new starter MCP server file")
+    p_init.add_argument("name", nargs="?", default="my-tools", help="Name of your MCP server")
+    p_init.add_argument("-o", "--output", default="server.py", help="Output file path (default: server.py)")
+    p_init.add_argument("-f", "--force", action="store_true", help="Overwrite existing file")
+    p_init.set_defaults(func=cmd_init)
+
+    # config
+    p_cfg = subparsers.add_parser("config", help="Generate Claude Desktop config JSON for an existing script")
+    p_cfg.add_argument("script", help="Path to your python MCP server script")
+    p_cfg.set_defaults(func=cmd_config)
+
+    args = parser.parse_args(argv)
+    if not args.subcommand:
+        parser.print_help()
+        return 0
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

easy_mcp/protocol.py

@@ -0,0 +1,92 @@
+"""
+Model Context Protocol (MCP) and JSON-RPC 2.0 specifications.
+Standard specification: https://spec.modelcontextprotocol.io/
+Zero external dependencies.
+"""
+
+from typing import Any, Dict, Optional
+
+JSONRPC_VERSION = "2.0"
+MCP_PROTOCOL_VERSION = "2024-11-05"
+
+# Standard JSON-RPC Error Codes
+PARSE_ERROR = -32700
+INVALID_REQUEST = -32600
+METHOD_NOT_FOUND = -32601
+INVALID_PARAMS = -32602
+INTERNAL_ERROR = -32603
+
+# Standard MCP Methods
+METHOD_INITIALIZE = "initialize"
+METHOD_INITIALIZED = "notifications/initialized"
+METHOD_PING = "ping"
+METHOD_TOOLS_LIST = "tools/list"
+METHOD_TOOLS_CALL = "tools/call"
+METHOD_RESOURCES_LIST = "resources/list"
+METHOD_RESOURCES_READ = "resources/read"
+METHOD_PROMPTS_LIST = "prompts/list"
+METHOD_PROMPTS_GET = "prompts/get"
+
+
+class MCPError(Exception):
+    """Base exception for MCP and JSON-RPC errors."""
+
+    def __init__(self, code: int, message: str, data: Any = None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.data = data
+
+
+class ParseError(MCPError):
+    def __init__(self, message: str = "Parse error", data: Any = None):
+        super().__init__(PARSE_ERROR, message, data)
+
+
+class InvalidRequestError(MCPError):
+    def __init__(self, message: str = "Invalid Request", data: Any = None):
+        super().__init__(INVALID_REQUEST, message, data)
+
+
+class MethodNotFoundError(MCPError):
+    def __init__(self, message: str = "Method not found", data: Any = None):
+        super().__init__(METHOD_NOT_FOUND, message, data)
+
+
+class InvalidParamsError(MCPError):
+    def __init__(self, message: str = "Invalid params", data: Any = None):
+        super().__init__(INVALID_PARAMS, message, data)
+
+
+class InternalError(MCPError):
+    def __init__(self, message: str = "Internal error", data: Any = None):
+        super().__init__(INTERNAL_ERROR, message, data)
+
+
+def make_jsonrpc_response(request_id: Any, result: Any) -> Dict[str, Any]:
+    """Build a compliant JSON-RPC 2.0 response."""
+    return {
+        "jsonrpc": JSONRPC_VERSION,
+        "id": request_id,
+        "result": result
+    }
+
+
+def make_jsonrpc_error(
+    request_id: Any,
+    code: int,
+    message: str,
+    data: Optional[Any] = None
+) -> Dict[str, Any]:
+    """Build a compliant JSON-RPC 2.0 error response."""
+    err: Dict[str, Any] = {
+        "code": code,
+        "message": message
+    }
+    if data is not None:
+        err["data"] = data
+    return {
+        "jsonrpc": JSONRPC_VERSION,
+        "id": request_id,
+        "error": err
+    }

easy_mcp/schema.py

@@ -0,0 +1,158 @@
+"""
+Automatic JSON Schema generator from Python function signatures and docstrings.
+Zero external dependencies.
+"""
+
+import inspect
+import re
+from typing import Any, Callable, Dict, List, Optional, Tuple, get_type_hints
+
+TYPE_MAP = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+    list: "array",
+    dict: "object",
+}
+
+
+def python_type_to_json_type(py_type: Any) -> str:
+    """Map Python types and type hints to JSON schema types."""
+    if py_type in TYPE_MAP:
+        return TYPE_MAP[py_type]
+
+    # Handle typing constructs or strings
+    type_str = str(py_type).lower()
+    if "str" in type_str:
+        return "string"
+    if "int" in type_str:
+        return "integer"
+    if "float" in type_str:
+        return "number"
+    if "bool" in type_str:
+        return "boolean"
+    if "list" in type_str or "sequence" in type_str:
+        return "array"
+    if "dict" in type_str or "mapping" in type_str:
+        return "object"
+
+    return "string"
+
+
+def parse_docstring(docstring: Optional[str]) -> Tuple[str, Dict[str, str]]:
+    """
+    Extract main description and parameter descriptions from docstrings.
+    Supports Google, Sphinx, and standard docstrings.
+    """
+    if not docstring:
+        return "", {}
+
+    lines = docstring.strip().splitlines()
+    desc_lines = []
+    param_docs: Dict[str, str] = {}
+
+    in_args_section = False
+    current_param = None
+
+    for line in lines:
+        stripped = line.strip()
+        if re.match(r"^(Args|Parameters|Arguments):", stripped, re.IGNORECASE):
+            in_args_section = True
+            continue
+
+        if in_args_section:
+            # Check for param line: "param_name: description" or "param_name (type): description"
+            m = re.match(r"^([a-zA-Z_][a-zA-Z0-9_]*)(?:\s*\([^)]+\))?:\s*(.+)$", stripped)
+            if m:
+                current_param = m.group(1)
+                param_docs[current_param] = m.group(2).strip()
+            elif current_param and stripped:
+                # Continuation line
+                param_docs[current_param] += " " + stripped
+        else:
+            desc_lines.append(stripped)
+
+    main_desc = " ".join(desc_lines).strip()
+    return main_desc, param_docs
+
+
+def function_to_tool_schema(
+    func: Callable,
+    name: Optional[str] = None,
+    description: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Inspect a Python callable and convert it to an MCP tool definition with JSON Schema inputSchema.
+    """
+    tool_name = name or func.__name__
+    raw_doc = inspect.getdoc(func) or ""
+    main_desc, param_docs = parse_docstring(raw_doc)
+    tool_desc = description or main_desc or f"Tool: {tool_name}"
+
+    sig = inspect.signature(func)
+    try:
+        type_hints = get_type_hints(func)
+    except Exception:
+        type_hints = {}
+
+    properties: Dict[str, Any] = {}
+    required: List[str] = []
+
+    for param_name, param in sig.parameters.items():
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            continue
+
+        param_type = type_hints.get(param_name, str)
+        json_type = python_type_to_json_type(param_type)
+
+        prop_def: Dict[str, Any] = {"type": json_type}
+
+        if param_name in param_docs:
+            prop_def["description"] = param_docs[param_name]
+
+        if param.default is not inspect.Parameter.empty:
+            prop_def["default"] = param.default
+        else:
+            required.append(param_name)
+
+        properties[param_name] = prop_def
+
+    input_schema: Dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+    }
+    if required:
+        input_schema["required"] = required
+
+    return {
+        "name": tool_name,
+        "description": tool_desc,
+        "inputSchema": input_schema
+    }
+
+
+def function_to_prompt_arguments(func: Callable) -> List[Dict[str, Any]]:
+    """
+    Inspect a Python callable and generate MCP prompt arguments list.
+    """
+    raw_doc = inspect.getdoc(func) or ""
+    _, param_docs = parse_docstring(raw_doc)
+
+    sig = inspect.signature(func)
+    arguments: List[Dict[str, Any]] = []
+
+    for param_name, param in sig.parameters.items():
+        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+            continue
+
+        arg_def: Dict[str, Any] = {
+            "name": param_name,
+            "required": (param.default is inspect.Parameter.empty),
+        }
+        if param_name in param_docs:
+            arg_def["description"] = param_docs[param_name]
+
+        arguments.append(arg_def)
+
+    return arguments

easy_mcp/server.py

@@ -0,0 +1,444 @@
+"""
+Core EasyMCP Server implementation.
+Handles stdio JSON-RPC 2.0 communication with Claude Desktop / Claude Code.
+Implements Model Context Protocol (MCP) 2024-11-05 Specification for Tools, Resources, and Prompts.
+Zero external dependencies.
+"""
+
+import json
+import os
+import sys
+import traceback
+from typing import Any, Callable, Dict, List, Optional
+
+from easy_mcp.protocol import (
+    INTERNAL_ERROR,
+    INVALID_PARAMS,
+    INVALID_REQUEST,
+    MCP_PROTOCOL_VERSION,
+    METHOD_INITIALIZE,
+    METHOD_INITIALIZED,
+    METHOD_NOT_FOUND,
+    METHOD_PING,
+    METHOD_PROMPTS_GET,
+    METHOD_PROMPTS_LIST,
+    METHOD_RESOURCES_LIST,
+    METHOD_RESOURCES_READ,
+    METHOD_TOOLS_CALL,
+    METHOD_TOOLS_LIST,
+    PARSE_ERROR,
+    make_jsonrpc_error,
+    make_jsonrpc_response,
+)
+from easy_mcp.schema import function_to_prompt_arguments, function_to_tool_schema
+
+
+class EasyMCP:
+    """
+    Lightweight, zero-dependency Model Context Protocol (MCP) Server.
+    
+    Example:
+        mcp = EasyMCP("my-server", version="0.2.0")
+
+        @mcp.tool()
+        def add(a: float, b: float) -> float:
+            '''Add two numbers together.'''
+            return a + b
+
+        @mcp.resource("memo://notes")
+        def get_notes() -> str:
+            '''System documentation notes.'''
+            return "Server documentation and quick guides."
+
+        @mcp.prompt()
+        def code_review(code: str) -> str:
+            '''Review code for safety and style.'''
+            return f"Please review this code for security issues:\n\n{code}"
+
+        if __name__ == "__main__":
+            mcp.run()
+    """
+
+    def __init__(
+        self,
+        name: str = "easy-mcp-server",
+        version: str = "0.2.0",
+        description: str = ""
+    ):
+        self.name = name
+        self.version = version
+        self.description = description
+        
+        self._tools: Dict[str, Callable] = {}
+        self._tool_schemas: Dict[str, Dict[str, Any]] = {}
+        
+        self._resources: Dict[str, Callable] = {}
+        self._resource_meta: Dict[str, Dict[str, Any]] = {}
+        
+        self._prompts: Dict[str, Callable] = {}
+        self._prompt_meta: Dict[str, Dict[str, Any]] = {}
+
+    # ==========================================
+    # Tools API
+    # ==========================================
+
+    def tool(self, name: Optional[str] = None, description: Optional[str] = None):
+        """Decorator to register a Python function as an MCP tool."""
+        def decorator(func: Callable):
+            self.register_tool(func, name=name, description=description)
+            return func
+        return decorator
+
+    def register_tool(
+        self,
+        func: Callable,
+        name: Optional[str] = None,
+        description: Optional[str] = None
+    ):
+        """Programmatic registration of an MCP tool."""
+        tool_name = name or func.__name__
+        schema = function_to_tool_schema(func, name=tool_name, description=description)
+        self._tools[tool_name] = func
+        self._tool_schemas[tool_name] = schema
+
+    def list_tools(self) -> List[Dict[str, Any]]:
+        """Return list of registered MCP tools."""
+        return list(self._tool_schemas.values())
+
+    def call_tool(self, name: str, arguments: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Execute a tool locally and return MCP content block result."""
+        if name not in self._tools:
+            raise KeyError(f"Tool '{name}' not found.")
+
+        args = arguments or {}
+        func = self._tools[name]
+
+        try:
+            res = func(**args)
+
+            if isinstance(res, (dict, list)):
+                text_content = json.dumps(res, ensure_ascii=False, indent=2)
+            else:
+                text_content = str(res)
+
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": text_content
+                    }
+                ],
+                "isError": False
+            }
+        except Exception as e:
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": f"Error executing tool '{name}': {str(e)}\n{traceback.format_exc()}"
+                    }
+                ],
+                "isError": True
+            }
+
+    # ==========================================
+    # Resources API
+    # ==========================================
+
+    def resource(
+        self,
+        uri: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        mime_type: str = "text/plain"
+    ):
+        """Decorator to register a function as an MCP resource provider."""
+        def decorator(func: Callable):
+            self.register_resource(
+                uri=uri,
+                func=func,
+                name=name,
+                description=description,
+                mime_type=mime_type
+            )
+            return func
+        return decorator
+
+    def register_resource(
+        self,
+        uri: str,
+        func: Callable,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        mime_type: str = "text/plain"
+    ):
+        """Programmatic registration of an MCP resource."""
+        res_name = name or uri
+        doc = (func.__doc__ or "").strip()
+        res_desc = description or doc or f"Resource: {res_name}"
+
+        self._resources[uri] = func
+        self._resource_meta[uri] = {
+            "uri": uri,
+            "name": res_name,
+            "description": res_desc,
+            "mimeType": mime_type,
+        }
+
+    def list_resources(self) -> List[Dict[str, Any]]:
+        """Return list of registered MCP resources."""
+        return list(self._resource_meta.values())
+
+    def read_resource(self, uri: str) -> Dict[str, Any]:
+        """Read an MCP resource by URI."""
+        if uri not in self._resources:
+            raise KeyError(f"Resource '{uri}' not found.")
+
+        meta = self._resource_meta[uri]
+        func = self._resources[uri]
+        
+        # Function may take 0 or 1 argument (uri)
+        import inspect
+        sig = inspect.signature(func)
+        if len(sig.parameters) == 1:
+            data = func(uri)
+        else:
+            data = func()
+
+        if isinstance(data, (dict, list)):
+            text_data = json.dumps(data, ensure_ascii=False, indent=2)
+        else:
+            text_data = str(data)
+
+        return {
+            "contents": [
+                {
+                    "uri": uri,
+                    "mimeType": meta.get("mimeType", "text/plain"),
+                    "text": text_data
+                }
+            ]
+        }
+
+    # ==========================================
+    # Prompts API
+    # ==========================================
+
+    def prompt(
+        self,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        arguments: Optional[List[Dict[str, Any]]] = None
+    ):
+        """Decorator to register a prompt template generator."""
+        def decorator(func: Callable):
+            self.register_prompt(
+                func=func,
+                name=name,
+                description=description,
+                arguments=arguments
+            )
+            return func
+        return decorator
+
+    def register_prompt(
+        self,
+        func: Callable,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        arguments: Optional[List[Dict[str, Any]]] = None
+    ):
+        """Programmatic registration of an MCP prompt."""
+        prompt_name = name or func.__name__
+        doc = (func.__doc__ or "").strip()
+        prompt_desc = description or doc or f"Prompt: {prompt_name}"
+        args_list = arguments if arguments is not None else function_to_prompt_arguments(func)
+
+        self._prompts[prompt_name] = func
+        self._prompt_meta[prompt_name] = {
+            "name": prompt_name,
+            "description": prompt_desc,
+            "arguments": args_list
+        }
+
+    def list_prompts(self) -> List[Dict[str, Any]]:
+        """Return list of registered MCP prompts."""
+        return list(self._prompt_meta.values())
+
+    def get_prompt(self, name: str, arguments: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Execute a prompt template and return MCP prompt response."""
+        if name not in self._prompts:
+            raise KeyError(f"Prompt '{name}' not found.")
+
+        meta = self._prompt_meta[name]
+        func = self._prompts[name]
+        args = arguments or {}
+
+        res = func(**args)
+
+        # Normalize result into list of messages
+        if isinstance(res, list):
+            messages = res
+        elif isinstance(res, str):
+            messages = [
+                {
+                    "role": "user",
+                    "content": {
+                        "type": "text",
+                        "text": res
+                    }
+                }
+            ]
+        elif isinstance(res, dict) and "messages" in res:
+            return res
+        else:
+            messages = [
+                {
+                    "role": "user",
+                    "content": {
+                        "type": "text",
+                        "text": str(res)
+                    }
+                }
+            ]
+
+        return {
+            "description": meta.get("description", ""),
+            "messages": messages
+        }
+
+    # ==========================================
+    # JSON-RPC Request Dispatcher
+    # ==========================================
+
+    def handle_request(self, request_data: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """Handle a single JSON-RPC 2.0 request."""
+        if not isinstance(request_data, dict):
+            return make_jsonrpc_error(None, INVALID_REQUEST, "Invalid JSON-RPC request structure.")
+
+        req_id = request_data.get("id")
+        method = request_data.get("method")
+        params = request_data.get("params", {})
+        is_notification = (req_id is None)
+
+        if not method or not isinstance(method, str):
+            return make_jsonrpc_error(req_id, INVALID_REQUEST, "Missing or invalid 'method' parameter.")
+
+        # 1. Initialize
+        if method == METHOD_INITIALIZE:
+            result = {
+                "protocolVersion": MCP_PROTOCOL_VERSION,
+                "capabilities": {
+                    "tools": {},
+                    "resources": {},
+                    "prompts": {}
+                },
+                "serverInfo": {
+                    "name": self.name,
+                    "version": self.version
+                }
+            }
+            return make_jsonrpc_response(req_id, result)
+
+        elif method == METHOD_INITIALIZED:
+            return None
+
+        # 2. Ping
+        elif method == METHOD_PING:
+            return make_jsonrpc_response(req_id, {})
+
+        # 3. Tools
+        elif method == METHOD_TOOLS_LIST:
+            return make_jsonrpc_response(req_id, {"tools": self.list_tools()})
+
+        elif method == METHOD_TOOLS_CALL:
+            tool_name = params.get("name")
+            arguments = params.get("arguments", {})
+            if not tool_name:
+                return make_jsonrpc_error(req_id, INVALID_PARAMS, "Missing required parameter: 'name'")
+            if tool_name not in self._tools:
+                return make_jsonrpc_error(req_id, METHOD_NOT_FOUND, f"Tool '{tool_name}' not found.")
+
+            res = self.call_tool(tool_name, arguments)
+            return make_jsonrpc_response(req_id, res)
+
+        # 4. Resources
+        elif method == METHOD_RESOURCES_LIST:
+            return make_jsonrpc_response(req_id, {"resources": self.list_resources()})
+
+        elif method == METHOD_RESOURCES_READ:
+            uri = params.get("uri")
+            if not uri:
+                return make_jsonrpc_error(req_id, INVALID_PARAMS, "Missing required parameter: 'uri'")
+            if uri not in self._resources:
+                return make_jsonrpc_error(req_id, INVALID_PARAMS, f"Resource '{uri}' not found.")
+
+            try:
+                res = self.read_resource(uri)
+                return make_jsonrpc_response(req_id, res)
+            except Exception as e:
+                return make_jsonrpc_error(req_id, INTERNAL_ERROR, f"Error reading resource: {str(e)}")
+
+        # 5. Prompts
+        elif method == METHOD_PROMPTS_LIST:
+            return make_jsonrpc_response(req_id, {"prompts": self.list_prompts()})
+
+        elif method == METHOD_PROMPTS_GET:
+            prompt_name = params.get("name")
+            arguments = params.get("arguments", {})
+            if not prompt_name:
+                return make_jsonrpc_error(req_id, INVALID_PARAMS, "Missing required parameter: 'name'")
+            if prompt_name not in self._prompts:
+                return make_jsonrpc_error(req_id, METHOD_NOT_FOUND, f"Prompt '{prompt_name}' not found.")
+
+            try:
+                res = self.get_prompt(prompt_name, arguments)
+                return make_jsonrpc_response(req_id, res)
+            except Exception as e:
+                return make_jsonrpc_error(req_id, INTERNAL_ERROR, f"Error generating prompt: {str(e)}")
+
+        else:
+            if is_notification:
+                return None
+            return make_jsonrpc_error(req_id, METHOD_NOT_FOUND, f"Unknown method: '{method}'")
+
+    def run_stdio(self):
+        """Run the stdio JSON-RPC loop connecting with Claude Desktop."""
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+
+            try:
+                request_data = json.loads(line)
+            except json.JSONDecodeError as e:
+                err_resp = make_jsonrpc_error(None, PARSE_ERROR, f"JSON parse error: {str(e)}")
+                sys.stdout.write(json.dumps(err_resp) + "\n")
+                sys.stdout.flush()
+                continue
+
+            response = self.handle_request(request_data)
+            if response is not None:
+                sys.stdout.write(json.dumps(response, ensure_ascii=False) + "\n")
+                sys.stdout.flush()
+
+    def run(self):
+        """Alias for run_stdio."""
+        self.run_stdio()
+
+    def get_claude_config(self, script_path: Optional[str] = None) -> Dict[str, Any]:
+        """Generate the JSON snippet for claude_desktop_config.json."""
+        target_script = script_path or os.path.abspath(sys.argv[0])
+        return {
+            "mcpServers": {
+                self.name: {
+                    "command": "python",
+                    "args": [target_script]
+                }
+            }
+        }
+
+    def print_claude_config(self, script_path: Optional[str] = None):
+        """Print formatted JSON for Claude Desktop configuration."""
+        cfg = self.get_claude_config(script_path)
+        print(json.dumps(cfg, indent=2))

py_easy_mcp-0.2.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: py-easy-mcp
+Version: 0.2.0
+Summary: Ultra-lightweight, zero-dependency Python framework to build Model Context Protocol (MCP) servers for Claude.
+Project-URL: Homepage, https://github.com/lui01212/easy-mcp
+Project-URL: Repository, https://github.com/lui01212/easy-mcp.git
+Project-URL: Issues, https://github.com/lui01212/easy-mcp/issues
+Author-email: lui01212 <luynbv@glotechvn.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,anthropic,claude,json-rpc,llm,mcp,model-context-protocol,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# py-easy-mcp ⚡🤖
+
+[![PyPI version](https://img.shields.io/pypi/v/py-easy-mcp.svg)](https://pypi.org/project/py-easy-mcp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/py-easy-mcp.svg)](https://pypi.org/project/py-easy-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Tests](https://github.com/lui01212/easy-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/lui01212/easy-mcp/actions)
+[![good first issues](https://img.shields.io/github/issues/lui01212/easy-mcp/good%20first%20issue?label=good%20first%20issues&color=7057ff)](https://github.com/lui01212/easy-mcp/issues?q=is%3Aissue+state%3Aopen+label%3A%22good+first+issue%22)
+[![Hacktoberfest](https://img.shields.io/badge/Hacktoberfest-2024-ff7a59?logo=hacktoberfest)](https://hacktoberfest.com/)
+
+**Ultra-lightweight, zero-dependency Python framework for Model Context Protocol (MCP). Build MCP servers for Claude in seconds.**
+
+Turn standard Python functions into Model Context Protocol tools, resources, and prompt templates for **Claude Desktop** and **Claude Code** with simple decorators.
+
+---
+
+## ⚡ Why easy-mcp?
+
+- **Zero dependencies:** Written in 100% pure standard Python. No heavy ASGI servers, no complex async overhead.
+- **Full MCP Protocol Support (v0.2.0):** Supports Tools (`@mcp.tool()`), Resources (`@mcp.resource()`), and Prompt Templates (`@mcp.prompt()`).
+- **Pythonic & Simple:** Turn any Python function into an MCP primitive with clean decorators.
+- **Automatic Schema Inspection:** Docstrings and type annotations are automatically converted into standard JSON Schemas.
+- **Claude Desktop Ready:** Built-in config generator outputs the exact JSON configuration to paste into `claude_desktop_config.json`.
+- **Offline & Safe:** Standard I/O (stdio) JSON-RPC 2.0 communication.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install py-easy-mcp
+```
+
+---
+
+## 🚀 30-Second Quickstart
+
+### 1. Write your server (`my_server.py`)
+
+```python
+from easy_mcp import EasyMCP
+
+mcp = EasyMCP(name="my-server", version="0.2.0")
+
+# 1. Register a Tool
+@mcp.tool()
+def add(a: float, b: float) -> float:
+    """Add two numbers together.
+
+    Args:
+        a: First number
+        b: Second number
+    """
+    return a + b
+
+# 2. Register a Resource (readable context)
+@mcp.resource("memo://project-guidelines")
+def guidelines() -> str:
+    """Project engineering principles."""
+    return "1. Keep it simple.\n2. Zero external dependencies.\n3. Write clear tests."
+
+# 3. Register a Prompt Template
+@mcp.prompt()
+def code_review(code: str, language: str = "python") -> str:
+    """Review code for bugs and maintainability."""
+    return f"Please review this {language} snippet:\n\n{code}"
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+### 2. Add to Claude Desktop
+
+Generate the configuration snippet:
+
+```bash
+easy-mcp config my_server.py
+```
+
+Output:
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "python",
+      "args": [
+        "/path/to/my_server.py"
+      ]
+    }
+  }
+}
+```
+
+Paste this into your `claude_desktop_config.json`:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+Restart Claude Desktop, and your tools, resources, and prompts will appear!
+
+---
+
+## 🛠️ CLI Utilities
+
+Scaffold a new server in 1 second:
+```bash
+easy-mcp init weather-server
+```
+
+Generate config for Claude Desktop:
+```bash
+easy-mcp config server.py
+```
+
+---
+
+## 📂 Community MCP Examples (Help Wanted!)
+
+We are building a curated collection of lightweight MCP tool servers in `examples/`:
+- `examples/basic_math.py` - Math calculator
+- `examples/pii_shield_mcp.py` - AI data privacy sanitizer
+
+### Want to contribute?
+Help us add more examples for Hacktoberfest:
+- 🌐 SQLite database query tool
+- 📰 Hacker News API reader
+- 📁 Local markdown note searcher
+- ⛅ Weather lookup
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) to submit an example!
+
+---
+
+## 📄 License
+
+[MIT License](LICENSE) © 2026 lui01212

py_easy_mcp-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+easy_mcp/__init__.py,sha256=bvChmmQxYG5S22OiNR0-bxoQ-kBEiPasKYJTELjdHhg,675
+easy_mcp/cli.py,sha256=3wmh8ctsIoBM_HFFwFZ3OlZQwOCaeUK_9xXwEIVV9hA,3956
+easy_mcp/protocol.py,sha256=P7x7oiCxxg-yppg6Qj3z7JU2JlP-84QhhM0imVKWR4Y,2521
+easy_mcp/schema.py,sha256=dwzxMzV-rnqTJ2qPt8xve1PUzQNQuLJUNXR5YBBBr_c,4583
+easy_mcp/server.py,sha256=wmanDyfy7eEe09Rqi9ytiiLfrLc_LVOpUGBCio_I9j4,14810
+py_easy_mcp-0.2.0.dist-info/METADATA,sha256=qtdEhlsv8wPz7gxNBfgyppxRjTw16iu6sA8mqKhE2Ls,5314
+py_easy_mcp-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+py_easy_mcp-0.2.0.dist-info/entry_points.txt,sha256=pmY6wFwySLtIsCCY3SkEs2EMXPq-AnyIoQE0sfksJQM,79
+py_easy_mcp-0.2.0.dist-info/licenses/LICENSE,sha256=RWxza2uvDjCv6Rh2BuAIA6Y_trYT1WF7EZ5fUFYldWc,1065
+py_easy_mcp-0.2.0.dist-info/RECORD,,

py_easy_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

py_easy_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+easy-mcp = easy_mcp.cli:main
+py-easy-mcp = easy_mcp.cli:main

py_easy_mcp-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lui01212
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.