py-easy-mcp 0.2.0__tar.gz

py_easy_mcp-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,39 @@
+name: "🐛 Bug Report"
+description: File a bug report for easy-mcp.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report an issue with easy-mcp!
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear description of the issue or unexpected MCP behavior.
+    validations:
+      required: true
+  - type: textarea
+    id: client
+    attributes:
+      label: MCP Client
+      description: Which client is connecting? (e.g., Claude Desktop, Claude Code, Cursor, Custom Inspector)
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction Code Snippet
+      description: Minimal Python script reproducing the issue.
+      placeholder: |
+        from easy_mcp import EasyMCP
+        mcp = EasyMCP("test")
+        ...
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: OS version, Python version, easy-mcp version
+      placeholder: Windows 11 / macOS / Linux, Python 3.12, easy-mcp v0.2.0

py_easy_mcp-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: "💡 Feature Request"
+description: Propose a new MCP feature, protocol extension, or example.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        We welcome ideas to make building MCP servers even easier and more powerful!
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Motivation
+      description: What capability or MCP feature are you looking for?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed Solution or API Design
+      description: How should the Python API look? (e.g., decorator syntax, helper utility)
+    validations:
+      required: true
+  - type: textarea
+    id: client_compatibility
+    attributes:
+      label: Client Compatibility
+      description: Does this target Claude Desktop, Cursor, or general MCP clients?

py_easy_mcp-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## Description
+<!-- Briefly describe what this PR does, why it is needed, and link any related issues. -->
+Fixes #
+
+## Type of Change
+- [ ] ✨ New MCP capability (tools, resources, prompts, transports)
+- [ ] 🐛 Bug fix (JSON-RPC protocol compliance, schema generation)
+- [ ] 📝 Documentation & examples
+- [ ] 🧪 Tests improvement
+- [ ] ⚡ Performance improvement
+
+## Checklist
+- [ ] My code adheres to the project's zero-external-dependency rule for runtime code.
+- [ ] All unit tests pass locally with `python -m unittest discover -s tests`.
+- [ ] I have added new unit tests for any new features or bug fixes.
+- [ ] Tested against Claude Desktop or MCP JSON-RPC stdio protocol.

py_easy_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Run unit tests
+      run: |
+        python -m unittest discover tests
+
+    - name: Test CLI installation
+      run: |
+        pip install .
+        easy-mcp --version
+        easy-mcp config examples/basic_math.py

py_easy_mcp-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Build and upload to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.12"
+
+    - name: Install build tool
+      run: pip install build
+
+    - name: Build sdist and wheel
+      run: python -m build
+
+    - name: Publish package to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

py_easy_mcp-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.venv
+venv/
+ENV/
+.env
+.pytest_cache/
+.ruff_cache/

py_easy_mcp-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,114 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+luynbv@glotechvn.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+**Community Impact**: A violation through a single incident or series of
+actions.
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

py_easy_mcp-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing to easy-mcp
+
+Thank you for your interest in **easy-mcp**! We welcome contributions to make building Model Context Protocol servers as easy and accessible as possible.
+
+---
+
+## 🌟 Great First Issues
+
+- **Add an MCP server example in `examples/`:**
+  Build a small tool server (e.g., SQLite query, currency converter, file search, RSS reader).
+- **Add unit tests:**
+  Add test cases in `tests/test_server.py`.
+- **Improve schema parsing:**
+  Support additional type annotations in `easy_mcp/schema.py`.
+
+---
+
+## 🛠️ Development Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/<your-username>/easy-mcp.git
+   cd easy-mcp
+   ```
+
+2. **Zero external dependencies:**
+   `easy-mcp` is 100% standard library Python. No heavy external frameworks required!
+
+3. **Running tests:**
+   ```bash
+   python -m unittest discover tests
+   ```
+
+4. **Submitting changes:**
+   - Create a branch: `git checkout -b feat/add-sqlite-example`
+   - Test your changes: `python -m unittest`
+   - Commit with Conventional Commits: `git commit -m "feat(examples): add sqlite query mcp server"`
+   - Push and open a Pull Request!

py_easy_mcp-0.2.0/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.

py_easy_mcp-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,134 @@
+# 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/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",
+]