mcp-testkit 0.1.0__tar.gz

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

@@ -0,0 +1,111 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["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 package
+        run: pip install -e ".[dev]" 2>/dev/null || pip install -e . && pip install pytest
+
+      - name: Run tests
+        run: python -m pytest tests/ -v --tb=short
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: pip install -e . ruff
+
+      - name: Check formatting
+        run: ruff format --check .
+
+      - name: Check linting
+        run: ruff check .
+
+  integration:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package
+        run: pip install -e . pytest
+
+      - name: Verify CLI entry point
+        run: mcp-test-server --help
+
+      - name: Verify SSE server starts and responds
+        run: |
+          mcp-test-server --transport sse --port 3001 &
+          sleep 3
+          curl -sf http://127.0.0.1:3001/api-docs | python -c "import sys,json; d=json.load(sys.stdin); assert d['openapi']=='3.0.3'; assert len(d['paths'])==65"
+          curl -sf "http://127.0.0.1:3001/api/math/add?a=2&b=3" | python -c "import sys,json; d=json.load(sys.stdin); assert d['result']==5.0"
+          curl -sf -X POST http://127.0.0.1:3001/api/string/reverse -H 'Content-Type: application/json' -d '{"text":"hello"}' | python -c "import sys,json; d=json.load(sys.stdin); assert d['result']=='olleh'"
+          kill %1
+
+      - name: Verify auth mode
+        run: |
+          mcp-test-server --transport sse --port 3002 --auth testkey &
+          sleep 3
+          STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:3002/api/math/add?a=1\&b=2)
+          [ "$STATUS" = "401" ] || (echo "Expected 401, got $STATUS" && exit 1)
+          curl -sf -H "Authorization: Bearer testkey" "http://127.0.0.1:3002/api/math/add?a=1&b=2" | python -c "import sys,json; d=json.load(sys.stdin); assert d['result']==3.0"
+          kill %1
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [test, lint]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Verify wheel contents
+        run: |
+          pip install dist/*.whl
+          mcp-test-server --help
+          python -c "from mcp_test_server import __version__; print(f'Version: {__version__}')"
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

mcp_testkit-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/

mcp_testkit-0.1.0/AGENTS.md

@@ -0,0 +1,148 @@
+# Agent Contributing Guide
+
+Instructions for AI agents contributing to this project.
+
+## Project Overview
+
+This is an MCP test server with 65 deterministic tools across 8 groups, exposed via MCP (stdio/SSE) and REST API. Every tool returns identical output for identical input — no randomness, no `datetime.now()`, no external state.
+
+## Architecture
+
+```
+mcp_test_server/
+  server.py      → Entry point. Creates FastMCP instance, registers tools, starts transport.
+  api.py         → REST API. Data-driven endpoint registry generates Starlette routes + OpenAPI spec.
+  tools/*.py     → Tool modules. Each exports register(mcp) that decorates tools with @mcp.tool().
+tests/*.py       → Unit + integration tests using unittest + FastMCP's call_tool().
+```
+
+**Key pattern:** Tools are registered as closures inside `register(mcp)` via `@mcp.tool()` decorators. Helper functions live at module level.
+
+## How to Add a New Tool
+
+### 1. Choose the right module
+
+| Group | File | When to use |
+|-------|------|-------------|
+| math | `mcp_test_server/tools/math_tools.py` | Numeric computation |
+| string | `mcp_test_server/tools/string_tools.py` | String manipulation |
+| collection | `mcp_test_server/tools/collection_tools.py` | Array/dict operations |
+| encoding | `mcp_test_server/tools/encoding_tools.py` | Encode/decode/hash |
+| datetime | `mcp_test_server/tools/datetime_tools.py` | Date computations (no current time!) |
+| validation | `mcp_test_server/tools/validation_tools.py` | Input checking (returns `{valid, reason}`) |
+| conversion | `mcp_test_server/tools/conversion_tools.py` | Unit/format conversions |
+| echo | `mcp_test_server/tools/echo_tools.py` | Protocol testing, fixtures, misc |
+
+If a tool doesn't fit any group, add it to `mcp_test_server/tools/echo_tools.py` (the catch-all for test fixtures).
+
+### 2. Implement the tool
+
+Add it inside the `register(mcp)` function in the chosen module:
+
+```python
+@mcp.tool()
+def my_new_tool(param: str, count: int) -> str:
+    """Clear one-line description of what the tool does."""
+    result = param * count
+    return json.dumps({"result": result})
+```
+
+Rules:
+- **Return JSON strings** via `json.dumps({"result": ...})` for success
+- **Return error objects** via `json.dumps({"error": "message"})` for expected errors
+- **Raise `ToolError`** only for tools that intentionally test error handling
+- **Be deterministic** — no randomness, no current time, no network calls, no file I/O
+- **Use stdlib only** — no imports beyond Python stdlib + `mcp` + `requests`
+- **Type-annotate all parameters** — FastMCP uses these to generate JSON schemas
+- Validation tools return `json.dumps({"valid": bool, "reason": str})`
+
+### 3. Add the REST API endpoint
+
+In `mcp_test_server/api.py`, add an entry to the `ENDPOINTS` list:
+
+```python
+# For GET (simple scalar params):
+("/api/group/my-tool", "GET", "my_new_tool",
+ "Description for OpenAPI",
+ [("param", "string", True, "Param description"),
+  ("count", "integer", True, "Count description")]),
+
+# For POST (complex or text-heavy params):
+("/api/group/my-tool", "POST", "my_new_tool",
+ "Description for OpenAPI",
+ [("param", "string", True, "Param description"),
+  ("count", "integer", True, "Count description")]),
+```
+
+The tuple format is: `(path, method, tool_name, summary, params)` where params is `[(name, json_schema_type, required, description), ...]`.
+
+Use GET for simple scalar inputs. Use POST for text bodies, arrays, objects, or anything complex.
+
+The route handler and OpenAPI spec are generated automatically from this entry.
+
+### 4. Write tests
+
+Add tests in the corresponding `tests/test_<group>_tools.py`:
+
+```python
+def test_my_new_tool(self):
+    result = _call(self.mcp, "my_new_tool", {"param": "abc", "count": 3})
+    self.assertEqual(result, {"result": "abcabcabc"})
+```
+
+Also add an API test in `tests/test_api.py`:
+
+```python
+def test_my_new_tool(self):
+    r = self.client.post("/api/group/my-tool", json={"param": "abc", "count": 3})
+    self.assertEqual(r.json(), {"result": "abcabcabc"})
+```
+
+### 5. Update integration test
+
+In `tests/test_integration.py`, update the expected tool count in `test_all_65_tools_registered` and adjust group counts if applicable.
+
+### 6. Verify
+
+```bash
+python3 -m pytest tests/ -v
+```
+
+All tests must pass. Current count: 389 tests.
+
+## How to Add a New Tool Group
+
+1. Create `mcp_test_server/tools/new_group_tools.py` with a `register(mcp)` function
+2. Import it in `mcp_test_server/tools/__init__.py` and add to `ALL_GROUPS`
+3. Add REST endpoints in `mcp_test_server/api.py` `ENDPOINTS` list
+4. Create `tests/test_new_group_tools.py`
+5. Update `tests/test_integration.py` tool counts and prefix checks
+
+## Conventions
+
+- **Tool names**: `group_action` (e.g., `math_add`, `string_reverse`)
+- **API paths**: `/api/group/action-name` with kebab-case (e.g., `/api/math/add`, `/api/string/char-count`)
+- **Responses**: Always JSON. Success: `{"result": ...}`. Error: `{"error": "message"}`. Validation: `{"valid": bool, "reason": str}`.
+- **No external state**: Tools must be pure functions of their inputs
+- **Test helpers**: Use `_make_server()` and `_call(mcp, name, args)` pattern (see existing tests)
+
+## Running the Server
+
+```bash
+# stdio (for MCP client testing)
+mcp-test-server
+
+# SSE + REST API
+mcp-test-server --transport sse
+
+# With auth
+mcp-test-server --transport sse --auth <key>
+```
+
+Default SSE port is 3001. Override with `--port`.
+
+## Dependencies
+
+Runtime: `mcp[cli]`, `requests`, Python stdlib.
+
+The server must not add dependencies beyond these. Use stdlib for all tool implementations.

mcp_testkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentSpan
+
+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_testkit-0.1.0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: mcp-testkit
+Version: 0.1.0
+Summary: MCP test server with 65 deterministic tools for protocol testing
+Project-URL: Repository, https://github.com/agentspan-dev/mcp-test-server
+Author: AgentSpan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: mcp,model-context-protocol,testing,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: requests
+Description-Content-Type: text/markdown
+
+# MCP Test Server
+
+A Python MCP server with **65 deterministic tools** across 8 groups, supporting **stdio**, **SSE**, and **REST API** transports. Built for consistent, repeatable MCP protocol testing.
+
+## Install
+
+```bash
+pip install mcp-testkit
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/agentspan-dev/mcp-test-server.git
+cd mcp-test-server
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# stdio (default)
+mcp-test-server
+
+# SSE + REST API on port 3001
+mcp-test-server --transport sse
+
+# With bearer token authentication
+mcp-test-server --transport sse --auth super_secret_key
+
+# Custom host/port
+mcp-test-server --transport sse --host 0.0.0.0 --port 8080
+```
+
+## Transports
+
+| Transport | Command | Endpoints |
+|-----------|---------|-----------|
+| **stdio** | `python3 server.py` | MCP JSON-RPC over stdin/stdout |
+| **SSE** | `python3 server.py --transport sse` | MCP at `/sse` + REST at `/api/*` + OpenAPI at `/api-docs` |
+
+## Authentication
+
+Pass `--auth <key>` to require a Bearer token on all requests (both MCP SSE and REST):
+
+```bash
+python3 server.py --transport sse --auth my_secret
+
+# Clients must include:
+# Authorization: Bearer my_secret
+```
+
+## Tools (65 total)
+
+All tools are **deterministic** — same input always produces same output. No randomness, no current time, no external state.
+
+### Math (8 tools)
+
+| Tool | Params | Description |
+|------|--------|-------------|
+| `math_add` | `a`, `b` | Add two numbers |
+| `math_subtract` | `a`, `b` | Subtract b from a |
+| `math_multiply` | `a`, `b` | Multiply two numbers |
+| `math_divide` | `a`, `b` | Divide (errors on zero) |
+| `math_modulo` | `a`, `b` | Remainder (errors on zero) |
+| `math_power` | `base`, `exponent` | Exponentiation |
+| `math_factorial` | `n` | n! (errors on negative) |
+| `math_fibonacci` | `n` | Nth Fibonacci number (0-indexed) |
+
+### String (8 tools)
+
+| Tool | Params | Description |
+|------|--------|-------------|
+| `string_reverse` | `text` | Reverse a string |
+| `string_uppercase` | `text` | Convert to uppercase |
+| `string_lowercase` | `text` | Convert to lowercase |
+| `string_length` | `text` | Character count |
+| `string_char_count` | `text`, `char` | Count occurrences |
+| `string_replace` | `text`, `old`, `new` | Replace all occurrences |
+| `string_split` | `text`, `delimiter` | Split by delimiter |
+| `string_join` | `items`, `delimiter` | Join list with delimiter |
+
+### Collection (8 tools)
+
+| Tool | Params | Description |
+|------|--------|-------------|
+| `collection_sort` | `items`, `reverse?` | Sort a list |
+| `collection_flatten` | `items` | Recursively flatten nested lists |
+| `collection_merge` | `dict_a`, `dict_b` | Merge dicts (b wins on conflict) |
+| `collection_filter_gt` | `items`, `threshold` | Filter numbers > threshold |
+| `collection_unique` | `items` | Remove duplicates (order preserved) |
+| `collection_group_by` | `items`, `key` | Group objects by key |
+| `collection_zip` | `list_a`, `list_b` | Zip into list of pairs |
+| `collection_chunk` | `items`, `size` | Split into chunks |
+
+### Encoding (8 tools)
+
+| Tool | Params | Description |
+|------|--------|-------------|
+| `encoding_base64_encode` | `text` | Base64 encode |
+| `encoding_base64_decode` | `data` | Base64 decode |
+| `encoding_url_encode` | `text` | URL-encode |
+| `encoding_url_decode` | `text` | URL-decode |
+| `encoding_hex_encode` | `text` | Hex encode |
+| `encoding_hex_decode` | `data` | Hex decode |
+| `encoding_md5` | `text` | MD5 hash |
+| `encoding_sha256` | `text` | SHA-256 hash |
+
+### DateTime (8 tools)
+
+All operate on provided dates — never use current time.
+
+| Tool | Params | Description |
+|------|--------|-------------|
+| `datetime_parse` | `date_string` | Parse ISO date to components |
+| `datetime_format` | `year`, `month`, `day`, `format` | Format date to string |
+| `datetime_add_days` | `date_string`, `days` | Add/subtract days |
+| `datetime_diff` | `date_a`, `date_b` | Days between two dates |
+| `datetime_day_of_week` | `date_string` | Weekday name |
+| `datetime_is_leap_year` | `year` | Leap year check |
+| `datetime_days_in_month` | `year`, `month` | Days in month |
+| `datetime_week_number` | `date_string` | ISO week number |
+
+### Validation (8 tools)
+
+All return `{valid: bool, reason: string}`.
+
+| Tool | Params | Description |
+|------|--------|-------------|
+| `validation_is_email` | `text` | Email format check |
+| `validation_is_url` | `text` | URL format check |
+| `validation_is_ipv4` | `text` | IPv4 address check |
+| `validation_is_ipv6` | `text` | IPv6 address check |
+| `validation_is_uuid` | `text` | UUID format check |
+| `validation_is_json` | `text` | Valid JSON check |
+| `validation_is_palindrome` | `text` | Palindrome check |
+| `validation_matches_regex` | `text`, `pattern` | Regex match check |
+
+### Conversion (8 tools)
+
+| Tool | Params | Description |
+|------|--------|-------------|
+| `conversion_celsius_to_fahrenheit` | `value` | C to F |
+| `conversion_fahrenheit_to_celsius` | `value` | F to C |
+| `conversion_km_to_miles` | `value` | km to miles |
+| `conversion_miles_to_km` | `value` | miles to km |
+| `conversion_bytes_to_human` | `bytes` | Bytes to human string |
+| `conversion_rgb_to_hex` | `r`, `g`, `b` | RGB to hex color |
+| `conversion_hex_to_rgb` | `hex_color` | Hex to RGB |
+| `conversion_decimal_to_binary` | `value` | Decimal to binary string |
+
+### Echo / Protocol Testing (8 tools)
+
+| Tool | Params | Description |
+|------|--------|-------------|
+| `echo` | `message` | Echo input unchanged |
+| `echo_error` | `message` | Always raises ToolError |
+| `echo_large` | `size_kb` | Deterministic ~N KB text |
+| `echo_nested` | `depth` | Nested JSON to depth N |
+| `echo_types` | — | All JSON types |
+| `echo_empty` | — | Empty string |
+| `echo_multiple` | `messages` | Multiple TextContent blocks |
+| `echo_schema` | `str_param`, `int_param`, `float_param`, `bool_param`, `list_param`, `obj_param` | Complex schema test |
+
+### Standalone
+
+| Tool | Params | Description |
+|------|--------|-------------|
+| `get_weather` | `city` | Fixed response: 77°F, sunny, always |
+
+## REST API
+
+When running with `--transport sse`, all tools are also available as HTTP endpoints:
+
+```bash
+# GET endpoints (math, conversion, some echo, weather)
+curl "http://localhost:3001/api/math/add?a=3&b=5"
+# {"result": 8.0}
+
+curl "http://localhost:3001/api/weather?city=NYC"
+# {"city":"NYC","temperature_f":77,...}
+
+# POST endpoints (string, collection, encoding, datetime, validation, some echo)
+curl -X POST "http://localhost:3001/api/string/reverse" \
+  -H "Content-Type: application/json" \
+  -d '{"text":"hello"}'
+# {"result": "olleh"}
+
+curl -X POST "http://localhost:3001/api/encoding/sha256" \
+  -H "Content-Type: application/json" \
+  -d '{"text":"hello"}'
+# {"result": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"}
+```
+
+**OpenAPI spec** at `GET /api-docs` (OpenAPI 3.0.3).
+
+With auth enabled, include `Authorization: Bearer <key>` on all requests.
+
+## Testing
+
+```bash
+python3 -m pytest tests/ -v
+```
+
+389 tests covering all tools, REST API endpoints, auth, OpenAPI spec, and integration.
+
+## Project Structure
+
+```
+mcp-test-server/
+├── pyproject.toml              # Package config, deps, CLI entry point
+├── mcp_test_server/
+│   ├── __init__.py             # Package version
+│   ├── server.py               # Entry point — MCP server + REST API + auth
+│   ├── api.py                  # REST API routes + OpenAPI spec generation
+│   └── tools/
+│       ├── __init__.py         # Tool group registry
+│       ├── math_tools.py
+│       ├── string_tools.py
+│       ├── collection_tools.py
+│       ├── encoding_tools.py
+│       ├── datetime_tools.py
+│       ├── validation_tools.py
+│       ├── conversion_tools.py
+│       └── echo_tools.py      # Includes get_weather
+└── tests/
+    ├── test_math_tools.py
+    ├── test_string_tools.py
+    ├── test_collection_tools.py
+    ├── test_encoding_tools.py
+    ├── test_datetime_tools.py
+    ├── test_validation_tools.py
+    ├── test_conversion_tools.py
+    ├── test_echo_tools.py
+    ├── test_api.py
+    └── test_integration.py
+```