From 48f546bf112a730196cb72a16d994846e356a7b8 Mon Sep 17 00:00:00 2001
From: AuraCrimsonRose <66587640+AuroraCrimsonRose@users.noreply.github.com>
Date: Wed, 27 May 2026 15:20:34 -0500
Subject: [PATCH] Add initial README for python-mcp project

This README provides an overview of the python-mcp project, including its features, core concepts, project structure, and getting started instructions.
---
 README.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 151 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..577bec0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,151 @@
+# python-mcp
+
+**python-mcp** is a lightweight, modular tool execution runtime written in Python.
+
+It enables registration and dynamic execution of tools (functions or modules) with a focus on simplicity, extensibility, and readiness for future MCP-style integrations. For development and rapid iteration, a local language model assists with debugging and code generation.
+
+---
+
+## Features
+
+- **Structured tool system**: Define and run discrete tools with minimal overhead
+- **Central tool registry**: Discover, register, and manage tools from a single place
+- **Isolated execution runtime**: Handles invocation, error management, and normalization
+- **Extensible transport**: Designed to support stdio, HTTP, and WebSocket interfaces in the future
+
+---
+
+## Core Concepts
+
+### Tools
+
+A **tool** is a function or module dedicated to a specific task.
+
+Key attributes:
+
+- `name`: Tool identifier (string)
+- `description`: Brief description
+- `execute`: Callable function to run the tool
+- `input schema` (optional): Schema for validating input
+
+**Example:**
+
+```python
+def example_tool(input: dict):
+    return {"result": "ok"}
+
+TOOL = {
+    "name": "example_tool",
+    "description": "Example tool",
+    "execute": example_tool,
+}
+```
+
+---
+
+### Registry
+
+The **registry** provides:
+
+- Tool registration (at startup or dynamically)
+- Listing of all available tools
+- Resolution and execution lookup by name
+
+---
+
+### Runtime
+
+The **runtime** manages:
+
+- Tool invocation and error isolation
+- Input/output normalization
+- Execution flow, including optional pre/post hooks
+
+---
+
+### Transport (Planned)
+
+Support for multiple interfaces is on the roadmap:
+
+- stdio (for local MCP clients)
+- HTTP API (remote integration)
+- WebSocket (streaming & interactive sessions)
+
+---
+
+## Project Structure
+
+Recommended directory layout:
+
+```
+core/         # Core framework logic, registries, interfaces
+runtime/      # Execution flow, runners, error handling
+registry/     # Tool registration and discovery utilities
+protocol/     # Data structure definitions and schemas
+transport/    # (Future) Interface implementations
+tools/        # Tool modules
+filesystem/   # Example tool domain
+system/       # Example tool domain
+network/      # Example tool domain
+server.py     # Main entry point
+```
+
+---
+
+## Getting Started
+
+1. **Create a virtual environment:**
+
+   ```sh
+   python -m venv .venv
+   ```
+
+2. **Activate the environment:**
+
+   - Windows:  
+     `.venv\Scripts\activate`
+   - Linux/macOS:  
+     `source .venv/bin/activate`
+
+3. **Install dependencies:**
+
+   ```sh
+   pip install -r requirements.txt
+   ```
+
+4. **Run the server:**
+
+   ```sh
+   python server.py
+   ```
+
+---
+
+## Adding a Tool
+
+- Place a Python file with your tool in the `tools/` directory.
+- Define your tool as shown in the example above.
+- Register your tool with the registry system.
+
+---
+
+## Notes
+
+- This project is in early development: expect rapid iteration and structural changes.
+- Tool definitions and the registry API may evolve.
+- Transport layer is currently unimplemented.
+- A local language model is used during development for coding, debugging, and accelerating iteration.
+
+---
+
+## Roadmap
+
+- [ ] Tool schema validation
+- [ ] Automatic tool discovery
+- [ ] MCP compatibility layer
+- [ ] Transport abstraction (stdio / HTTP)
+- [ ] Async execution support
+
+---
+
+Contributions and feedback are welcome!