http-mcp 0.0.1__tar.gz

http_mcp-0.0.1/.cursor/mcp.json

@@ -0,0 +1,14 @@
+{
+    "mcpServers": {
+        "test_studio": {
+            "command": "uv",
+            "args": [
+                "run",
+                "run-stdio"
+            ],
+            "env": {
+                "AUTHORIZATION_TOKEN": "Bearer TEST_TOKEN"
+            }
+        }
+    }
+}

http_mcp-0.0.1/.cursor/rules/python-style.mdc

@@ -0,0 +1,50 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+# Python Style Guide and Best Practices
+
+## Type Hints
+- All function parameters MUST have type hints
+- All function return values MUST have type hints
+- All class attributes MUST have type hints
+- Use `collections.abc` for abstract base classes (Sequence, Mapping, Set, etc.)
+- Use built-in types for simple type hints (str, int, bool, list, dict, etc.)
+- Use `type | None` instead of `Optional[type]`
+- Example:
+  ```python
+  from collections.abc import Sequence
+
+  def process_data(items: Sequence[str], max_items: int | None = None) -> dict[str, int]:
+      ...
+  ```
+
+## Functional Programming Paradigm
+- Prefer pure functions over methods with side effects
+- Use immutable data structures when possible, prefer tuples over lists
+- Avoid modifying function arguments
+- Use list/dict comprehensions instead of loops when possible
+- Minimize global state and mutable variables
+- Return new values instead of modifying existing ones
+- Example:
+  ```python
+  # Good - Pure function, immutable
+  def transform_data(data: list[int]) -> list[int]:
+      return [x * 2 for x in data if x > 0]
+
+  # Bad - Modifies input, has side effects
+  def transform_data(data: list[int]) -> None:
+      for i in range(len(data)):
+          data[i] *= 2
+  ```
+
+## Code Organization
+- Keep functions small and focused on a single responsibility
+- Use composition over inheritance
+- Prefer dependency injection over global state
+- Use descriptive variable names that reflect their purpose
+
+## Testing
+- Write unit tests for all pure functions
+- Test edge cases and error conditions

http_mcp-0.0.1/.envrc

@@ -0,0 +1,11 @@
+if [ -d .venv ]; then
+  source .venv/bin/activate
+  uv sync
+else
+  uv venv --python 3.13
+  source .venv/bin/activate
+fi
+
+echo Setting git hooksPath to .githooks
+chmod +x .githooks/pre-push
+git config core.hooksPath .githooks

http_mcp-0.0.1/.gemini/settings.json

@@ -0,0 +1,15 @@
+{
+  "autoAccept": false,
+  "contextFileName": "AGENT.md",
+  "usageStatisticsEnabled": true,
+  "respectGitIgnore": true,
+  "mcpServers": {
+    "test": {
+      "httpUrl": "http://localhost:8000/mcp/",
+      "timeout": 5000,
+      "headers": {
+        "Authorization": "Bearer TEST_TOKEN"
+      }
+    }
+  }
+}

http_mcp-0.0.1/.githooks/pre-push

@@ -0,0 +1 @@
+: && ruff check && mypy . &&  pytest --cov-report term-missing --cov=src --cov-fail-under=96 tests/ && mdformat . --wrap 80

http_mcp-0.0.1/.github/workflows/dev.yml

@@ -0,0 +1,40 @@
+permissions: read-all
+concurrency:
+  cancel-in-progress: true
+  group: ${{ github.actor }}
+
+jobs:
+  test:
+    name: test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest --cov=src --cov-fail-under=96 tests/
+
+      - name: Run mypy
+        run: uv run mypy . --config-file mypy.ini
+
+      - name: Run ruff
+        run: uv run ruff check .
+
+      - name: Run mdformat
+        run: uv run mdformat README.md --check --wrap 80
+
+name: dev
+on:
+  pull_request:
+    branches: [main]

http_mcp-0.0.1/.gitignore

@@ -0,0 +1,8 @@
+.venv
+.env
+.ruff_cache
+.mypy_cache
+.npm
+__pycache__
+.pytest_cache
+.coverage

http_mcp-0.0.1/.python-version

@@ -0,0 +1 @@
+3.13

http_mcp-0.0.1/.vscode/settings.json

@@ -0,0 +1,22 @@
+{
+  "[python]": {
+    "editor.codeActionsOnSave": {
+      "source.fixAll": "explicit",
+      "source.organizeImports": "explicit"
+    },
+    "editor.rulers": [100],
+    "editor.tabSize": 4,
+    "editor.defaultFormatter": "charliermarsh.ruff"
+  },
+  "mypy-type-checker.cwd": "/",
+  "ruff.configurationPreference": "filesystemFirst",
+  "ruff.organizeImports": true,
+  "ruff.lineLength": 100,
+  "mypy-type-checker.args": ["--explicit-package-bases", "--config-file", "mypy.ini"],
+  "python.testing.pytestArgs": [
+    "test",
+    "-vv"
+  ],
+  "python.testing.pytestEnabled": true,
+  "python.testing.unittestEnabled": false
+}

http_mcp-0.0.1/AGENT.md

@@ -0,0 +1,30 @@
+# Project
+
+## Project description
+
+This project is a base python project environment configuration using uv.
+
+## General Instructions:
+
+- When generating new python code, please follow the following coding style:
+  - Use 4 spaces for indentation.
+  - Use snake_case for variable names, functions, and parameters.
+  - Use PascalCase for class names.
+  - Prefer functional programming paradigms where appropriate.
+  - Use type hints for all functions, classes, and parameters as well as return
+    values.
+  - Use immutable data structures when possible, prefer tuples over lists.
+  - Avoid modifying function arguments.
+  - Use list/dict comprehensions instead of loops when possible.
+  - Minimize global state and mutable variables.
+  - Return new values instead of modifying existing ones.
+  - Keep functions small and focused on a single responsibility.
+
+## Tools usage
+
+- context7: when the user requests code examples, setup or configuration steps,
+  or library/API documentation, use this tool to generate the code.
+- file_reader: when the user requests to read a file, use this tool to read the
+  file.
+- safe_tool: when the user requests to run a command, use this tool to run the
+  command.

http_mcp-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yeison Liscano
+
+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.

http_mcp-0.0.1/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: http-mcp
+Version: 0.0.1
+Summary: This is a HTTP implementation of the MCP protocol
+Project-URL: Homepage, https://github.com/yeison-liscano/http_mcp
+Project-URL: Issues, https://github.com/yeison-liscano/http_mcp/issues
+Author-email: Yeison Liscano <yliscanoc@gmail.com>
+Maintainer-email: Yeison Liscano <yliscanoc@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,http,llm,mcp
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: <3.14,>=3.13
+Requires-Dist: pydantic==2.10.5
+Requires-Dist: starlette==0.47.2
+Requires-Dist: uvicorn==0.35.0
+Description-Content-Type: text/markdown
+
+# Simple HTTP MCP Server Implementation
+
+This project provides a lightweight server implementation for the Model Context
+Protocol (MCP) over HTTP. It allows you to expose Python functions as tools and
+prompts that can be discovered and executed remotely via a JSON-RPC interface.
+It is thought to be used with an Starlette or FastAPI application (see
+[app/main.py](app/main.py)).
+
+The following badge correspond to the server I use as example of of this
+project. Found it in the [app/ folder](app/main.py).
+
+<a href="https://glama.ai/mcp/servers/@yeison-liscano/http_mcp">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@yeison-liscano/http_mcp/badge" alt="Simple HTTP Server MCP server" />
+</a>
+
+## Features
+
+- **MCP Protocol Compliant**: Implements the MCP specification for tool and
+  prompts discovery and execution. No support for notifications.
+- **HTTP and STDIO Transport**: Uses HTTP (POST requests) or STDIO for
+  communication.
+- **Async Support**: Built on `Starlette` or `FastAPI` for asynchronous request
+  handling.
+- **Type-Safe**: Leverages `Pydantic` for robust data validation and
+  serialization.
+- **Stateful Context**: Maintain state across tool calls using a context object.
+- **Request Access**: Access the incoming request object from your tools.
+
+## Tools
+
+Tools are the functions that can be called by the client.
+
+Example:
+
+1. **Define the arguments and output for the tools:**
+
+```python
+# app/tools/models.py
+from pydantic import BaseModel, Field
+
+class ToolArguments(BaseModel):
+    question: str = Field(description="The question to answer")
+
+class ToolOutput(BaseModel):
+    answer: str = Field(description="The answer to the question")
+
+# Note: the description on Field will be passed when listing the tools.
+# Having a description is optional, but it's recommended to provide one.
+```
+
+2. **Define the tools:**
+
+```python
+# app/tools/tools.py
+import asyncio
+from pydantic import BaseModel, Field
+from http_mcp.tools import Tool, ToolArguments
+
+from app.tools.models import ToolArguments, ToolOutput
+
+def tool(args: ToolArguments[ToolArguments, None]) -> ToolOutput:
+    return ToolOutput(answer=f"Hello, {args.inputs.question}!") # access the inputs using args.inputs
+
+```
+
+```python
+# app/tools/__init__.py
+
+from app.tools.models import ToolArguments, ToolOutput
+from app.tools.tools import tool
+from http_mcp.tools import Tool
+
+TOOLS = (
+    Tool(
+        func=tool,
+        input=ToolArguments,
+        output=ToolOutput,
+    ),
+)
+
+__all__ = ["TOOLS"]
+
+```
+
+3. **Instantiate the server:**
+
+```python
+# app/main.py
+from starlette.applications import Starlette
+from http_mcp.server import MCPServer
+from app.tools import TOOLS
+
+mcp_server: MCPServer[None] = MCPServer(tools=TOOLS, name="test", version="1.0.0")
+
+app = Starlette()
+app.mount(
+    "/mcp",
+    mcp_server.app,
+)
+
+```
+
+## Stateful Context
+
+This is the server context attribute, it could be seem as a global state for the
+server.
+
+You can use a context object to maintain state across tool calls. The context
+object is passed to each tool call and can be used to store and retrieve data.
+
+Example:
+
+1. **Define a context class:**
+
+```python
+from dataclasses import dataclass, field
+
+@dataclass
+class Context:
+    called_tools: list[str] = field(default_factory=list)
+
+    def get_called_tools(self) -> list[str]:
+        return self.called_tools
+
+    def add_called_tool(self, tool_name: str) -> None:
+        self.called_tools.append(tool_name)
+```
+
+1. **Instantiate the context and the server:**
+
+```python
+from app.tools import TOOLS, Context
+from http_mcp.server import MCPServer
+
+mcp_server: MCPServer[Context] = MCPServer(
+    tools=TOOLS,
+    name="test",
+    version="1.0.0",
+    context=Context(called_tools=[]),
+)
+```
+
+1. **Access the context in your tools:**
+
+```python
+from pydantic import BaseModel, Field
+from http_mcp.tools import ToolArguments
+from app.tools import Context
+
+class MyToolArguments(BaseModel):
+    question: str = Field(description="The question to answer")
+
+class MyToolOutput(BaseModel):
+    answer: str = Field(description="The answer to the question")
+
+async def my_tool(args: ToolArguments[MyToolArguments, Context]) -> MyToolOutput:
+    # Access the context
+    args.context.add_called_tool("my_tool")
+    ...
+
+    return MyToolOutput(answer=f"Hello, {args.inputs.question}!")
+```
+
+## Stateless Context
+
+You can access the incoming request object from your tools. The request object
+is passed to each tool call and can be used to access headers, cookies, and
+other request data (e.x request.state, request.scope).
+
+```python
+from pydantic import BaseModel, Field
+from http_mcp.tools import ToolArguments
+
+class MyToolArguments(BaseModel):
+    question: str = Field(description="The question to answer")
+
+class MyToolOutput(BaseModel):
+    answer: str = Field(description="The answer to the question")
+
+
+async def my_tool(args: ToolArguments[MyToolArguments, None]) -> MyToolOutput:
+    # Access the request
+    auth_header = args.request.headers.get("Authorization")
+    ...
+
+    return MyToolOutput(answer=f"Hello, {args.inputs.question}!")
+```
+
+## Prompts
+
+You could add interactive templates that are invoked by user choice.
+
+1. **Define the arguments and output for the prompts:**
+
+```python
+from pydantic import BaseModel, Field
+
+from http_mcp.mcp_types.content import TextContent
+from http_mcp.mcp_types.prompts import PromptMessage
+from http_mcp.prompts import Prompt
+
+
+class GetAdvice(BaseModel):
+    topic: str = Field(description="The topic to get advice on")
+    include_actionable_steps: bool = Field(
+        description="Whether to include actionable steps in the advice", default=False
+    )
+
+
+def get_advice(args: GetAdvice) -> tuple[PromptMessage, ...]:
+    """Get advice on a topic."""
+    template = """
+    You are a helpful assistant that can give advice on {topic}.
+    """
+    if args.include_actionable_steps:
+        template += """
+        The advice should include actionable steps.
+        """
+    return (
+        PromptMessage(role="user", content=TextContent(text=template.format(topic=args.topic))),
+    )
+
+
+PROMPTS = (
+    Prompt(
+        func=get_advice,
+        arguments_type=GetAdvice,
+    ),
+)
+```
+
+2. **Instantiate the server:**
+
+```python
+from starlette.applications import Starlette
+
+from app.prompts import PROMPTS
+from http_mcp.server import MCPServer
+
+app = Starlette()
+mcp_server = MCPServer[None](tools=(), prompts=PROMPTS, name="test", version="1.0.0")
+
+app.mount(
+    "/mcp",
+    mcp_server.app,
+)
+
+```