mcp-server-forge 0.1.0__tar.gz

mcp_server_forge-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["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: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest --cov=mcp_forge --cov-report=term-missing
+
+      - name: Check types
+        run: |
+          pip install mypy
+          mypy src/mcp_forge --ignore-missing-imports
+        continue-on-error: true

mcp_server_forge-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/

mcp_server_forge-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing to MCP Forge
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Setup
+
+```bash
+git clone https://github.com/manasvardhan/mcp-forge.git
+cd mcp-forge
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest
+pytest --cov=mcp_forge
+```
+
+## Code Style
+
+- Python 3.10+ with type hints throughout
+- Use `from __future__ import annotations` in all modules
+- Follow PEP 8
+
+## Pull Requests
+
+1. Fork the repo and create a branch from `main`
+2. Add tests for any new functionality
+3. Make sure all tests pass
+4. Update documentation if needed
+5. Open a PR with a clear description
+
+## Reporting Issues
+
+Open an issue on GitHub with:
+
+- A clear description of the problem
+- Steps to reproduce
+- Expected vs actual behavior
+- Python version and OS
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

mcp_server_forge-0.1.0/GETTING_STARTED.md

@@ -0,0 +1,155 @@
+# Getting Started with mcp-forge
+
+A step-by-step guide to get up and running from scratch.
+
+## Prerequisites
+
+You need **Python 3.10 or newer** installed on your machine.
+
+**Check if you have Python:**
+```bash
+python3 --version
+```
+If you see `Python 3.10.x` or higher, you're good. If not, download it from [python.org](https://www.python.org/downloads/).
+
+## Step 1: Clone the repository
+
+```bash
+git clone https://github.com/ManasVardhan/mcp-forge.git
+cd mcp-forge
+```
+
+## Step 2: Create a virtual environment
+
+```bash
+python3 -m venv venv
+```
+
+**Activate it:**
+
+- **Mac/Linux:** `source venv/bin/activate`
+- **Windows:** `venv\Scripts\activate`
+
+## Step 3: Install the package
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Step 4: Run the tests
+
+```bash
+pytest tests/ -v
+```
+
+All 23 tests should pass.
+
+## Step 5: Try it out
+
+### 5a. Scaffold a new MCP server
+
+```bash
+mcp-forge new my-first-server --tools weather,calculator
+```
+
+This generates a complete MCP server project. Take a look at what was created:
+
+```bash
+ls -la my-first-server/
+```
+
+You should see:
+```
+my-first-server/
+  src/
+    server.py          # Main server with JSON-RPC handler
+    tools/
+      weather.py       # Weather tool stub
+      calculator.py    # Calculator tool stub
+  tests/
+    test_server.py     # Test file
+  pyproject.toml       # Package config
+  Dockerfile           # Container config
+  README.md            # Auto-generated docs
+```
+
+### 5b. Look at the generated server
+
+Open `my-first-server/src/server.py` in any text editor. You'll see a working MCP server with:
+- JSON-RPC stdio transport (how AI models communicate with MCP servers)
+- Tool handler routing
+- Proper error handling
+
+### 5c. Validate the server
+
+Check that the generated server follows the MCP specification:
+
+```bash
+mcp-forge validate my-first-server/
+```
+
+You should see all checks passing.
+
+### 5d. Test the server
+
+```bash
+mcp-forge test my-first-server/
+```
+
+This sends test JSON-RPC requests to your server and shows the responses.
+
+### 5e. Check out the example weather server
+
+There's a pre-built example in the repo:
+
+```bash
+ls examples/weather_server/
+```
+
+### 5f. Try different tool combinations
+
+```bash
+mcp-forge new api-server --tools search,translate,summarize
+```
+
+Each tool gets its own file with a stub implementation ready to fill in.
+
+## Step 6: Build your own MCP server
+
+1. Scaffold it:
+   ```bash
+   mcp-forge new my-custom-server --tools mytool
+   ```
+
+2. Edit `my-custom-server/src/tools/mytool.py` to add your logic
+
+3. Test it:
+   ```bash
+   mcp-forge test my-custom-server/
+   ```
+
+4. Validate it:
+   ```bash
+   mcp-forge validate my-custom-server/
+   ```
+
+## Step 7: Run the linter (optional)
+
+```bash
+ruff check src/ tests/
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `python3: command not found` | Install Python from [python.org](https://www.python.org/downloads/) |
+| `No module named mcp_forge` | Make sure you ran `pip install -e ".[dev]"` with the venv activated |
+| `mcp-forge: command not found` | Make sure your venv is activated |
+| Tests fail | Make sure you're on the latest `main` branch: `git pull origin main` |
+
+## What's next?
+
+- Read the full [README](README.md) for custom templates, publishing, and advanced options
+- Check `examples/weather_server/` for a complete working MCP server
+- Try connecting your MCP server to Claude Desktop or another MCP-compatible AI client

mcp_server_forge-0.1.0/LICENSE

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

mcp_server_forge-0.1.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: mcp-server-forge
+Version: 0.1.0
+Summary: Scaffold, test, and publish Model Context Protocol (MCP) servers in seconds
+Project-URL: Homepage, https://github.com/manasvardhan/mcp-forge
+Project-URL: Repository, https://github.com/manasvardhan/mcp-forge
+Project-URL: Issues, https://github.com/manasvardhan/mcp-forge/issues
+Author: Manas Vardhan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,cli,mcp,model-context-protocol,scaffold
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: click>=8.1
+Requires-Dist: jinja2>=3.1
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: publish
+Requires-Dist: build>=1.0; extra == 'publish'
+Requires-Dist: twine>=4.0; extra == 'publish'
+Description-Content-Type: text/markdown
+
+
+# 🔨 MCP Forge
+
+> **New here?** Start with the [Getting Started Guide](GETTING_STARTED.md).
+
+**Scaffold, test, and publish Model Context Protocol (MCP) servers in seconds.**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)]()
+[![PyPI](https://img.shields.io/badge/pypi-v0.1.0-orange.svg)]()
+
+---
+
+## The Problem
+
+Building MCP servers involves too much boilerplate. Every new server needs the same JSON-RPC handling, tool definitions, resource handlers, Dockerfile, tests, and packaging config. You end up copying from old projects, fixing import paths, and wasting time on plumbing instead of building.
+
+**MCP Forge fixes this.** One command generates a complete, ready-to-develop MCP server project. Another command tests it. Another validates compliance. Another publishes it.
+
+## Features
+
+- 🏗️ **Scaffold** full MCP server projects from templates in one command
+- 🧪 **Test** servers with a built-in MCP test harness (JSON-RPC over stdio)
+- 🔍 **Validate** server compliance against the MCP specification
+- 📦 **Publish** to PyPI with a single command
+- 🎨 **Jinja2-powered scaffolding** with clean, extensible templates
+- 🐳 **Dockerfile** included in every generated project
+- ⚡ **Zero config** needed for standard MCP servers
+
+## Quick Start
+
+### Install
+
+```bash
+pip install mcp-forge
+```
+
+### Create a new MCP server
+
+```bash
+mcp-forge new my-server --tools weather,calculator
+```
+
+That's it. You now have a complete, runnable MCP server:
+
+```
+my-server/
+├── Dockerfile
+├── README.md
+├── pyproject.toml
+├── .gitignore
+├── src/
+│   └── my_server/
+│       ├── __init__.py
+│       ├── server.py
+│       ├── tools.py
+│       └── resources.py
+└── tests/
+    └── test_my_server.py
+```
+
+### Test your server
+
+```bash
+cd my-server
+pip install -e .
+mcp-forge test --cmd 'python -m my_server.server'
+```
+
+```
+┌──────────────────────────────────────────────────┐
+│           MCP Forge Test Results                 │
+├──────────────┬────────┬──────────────────────────┤
+│ Test         │ Status │ Details                  │
+├──────────────┼────────┼──────────────────────────┤
+│ server_start │  PASS  │ Server started           │
+│ initialize   │  PASS  │ initialize response valid │
+│ tools/list   │  PASS  │ Found 2 tools            │
+│ tools/call   │  PASS  │ Called 'weather' OK      │
+│ ping         │  PASS  │ Ping OK                  │
+│ unknown      │  PASS  │ Correctly returned error │
+│ server_stop  │  PASS  │ Server stopped cleanly   │
+├──────────────┴────────┴──────────────────────────┤
+│ 7/7 passed  All tests passed!                    │
+└──────────────────────────────────────────────────┘
+```
+
+### Validate compliance
+
+```bash
+mcp-forge validate ./my-server
+```
+
+### Publish
+
+```bash
+mcp-forge publish ./my-server
+mcp-forge publish ./my-server --repository testpypi --dry-run
+```
+
+## Scaffolding
+
+The `new` command generates a complete MCP server with:
+
+- A fully functional `server.py` with JSON-RPC request routing
+- Tool definitions and handlers in `tools.py`
+- Resource handlers in `resources.py`
+- A `pyproject.toml` configured with hatchling
+- A `Dockerfile` for containerized deployment
+- A `README.md` with usage instructions
+- Basic tests and `.gitignore`
+
+### Options
+
+```bash
+mcp-forge new my-server \
+  --tools weather,calculator,search \
+  --resources "file://data,http://api" \
+  --description "My awesome MCP server" \
+  --author "Your Name" \
+  --output-dir ./projects
+```
+
+## Templates
+
+MCP Forge uses Jinja2 templates internally. Each generated file comes from a template in the `templates/` directory:
+
+| Template | Generates |
+|----------|-----------|
+| `server.py.j2` | Main server with JSON-RPC routing |
+| `tools.py.j2` | Tool definitions and handlers |
+| `resources.py.j2` | Resource definitions and handlers |
+| `project_pyproject.toml.j2` | Package configuration |
+| `project_readme.md.j2` | Project README |
+| `dockerfile.j2` | Docker container config |
+| `init.py.j2` | Package init file |
+
+## Testing
+
+The built-in test harness starts your MCP server as a subprocess and sends JSON-RPC requests over stdio, validating:
+
+- **Server startup** and clean shutdown
+- **initialize** response with protocol version, capabilities, and server info
+- **tools/list** returns valid tool definitions
+- **tools/call** executes a tool and returns content
+- **ping** responds correctly
+- **Unknown methods** return proper JSON-RPC errors
+
+## Validation
+
+The `validate` command checks your project for:
+
+- Required file structure (`src/`, `pyproject.toml`, `server.py`, `tools.py`)
+- Tool definitions match the MCP schema (name, description, inputSchema)
+- Initialize responses include all required fields
+- Tool results contain valid content arrays
+
+## Publishing
+
+The `publish` command wraps `build` and `twine` for a smooth publishing experience:
+
+```bash
+# Build and publish to PyPI
+mcp-forge publish .
+
+# Dry run (build only)
+mcp-forge publish . --dry-run
+
+# Publish to TestPyPI
+mcp-forge publish . --repository testpypi
+```
+
+Make sure you have `build` and `twine` installed:
+
+```bash
+pip install mcp-forge[publish]
+```
+
+## Template Customization
+
+The scaffolding uses Jinja2 templates internally. To customize the generated code, fork the repo and modify the templates in `src/mcp_forge/templates/`. The Jinja2 context includes:
+
+- `project_name` - the project name as given
+- `pkg_name` - Python package name (snake_case)
+- `title` - human readable title
+- `description` - project description
+- `author` - author name
+- `tools` - list of tool names
+- `resources` - list of resource URI patterns
+
+## Development
+
+```bash
+git clone https://github.com/manasvardhan/mcp-forge.git
+cd mcp-forge
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+Built with 🔨 by [Manas Vardhan](https://github.com/manasvardhan)