mcp-toolsmith 0.1.0a1__tar.gz

mcp_toolsmith-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest
+
+      - name: Run lint
+        run: ruff check .
+

mcp_toolsmith-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: |
+          pytest
+          ruff check .
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+

mcp_toolsmith-0.1.0a1/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+build/
+dist/
+*.egg-info/
+

mcp_toolsmith-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0a1
+
+- Add `mcp-toolsmith audit` for Python files and MCP JSON tool definitions.
+- Add `mcp-toolsmith compile` for MCP and OpenAI-style tool output.
+- Discover top-level Python functions and Pydantic v2 models.
+- Report naming, description, schema-size, argument-description, overlap, and
+  tool-poisoning findings.
+- Refuse Python file execution by default; use `--execute` only for trusted
+  Python files.
+- Preserve user properties named like JSON Schema metadata during compilation.

mcp_toolsmith-0.1.0a1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Shayan Mousavinia
+
+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_toolsmith-0.1.0a1/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: mcp-toolsmith
+Version: 0.1.0a1
+Summary: Audit and compile Python tool schemas for LLM agents.
+Project-URL: Repository, https://github.com/ShAmoNiA/mcp-toolsmith
+Project-URL: Issues, https://github.com/ShAmoNiA/mcp-toolsmith/issues
+Author: Shayan Mousavinia
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,json-schema,llm,mcp,pydantic,tool-calling
+Classifier: Development Status :: 3 - Alpha
+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 :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: jsonschema>=4.22
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: editables>=0.5; extra == 'dev'
+Requires-Dist: mypy<1.19,>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcp-toolsmith
+
+Audit and compile Python tool schemas for LLM agents.
+
+**Alpha:** JSON tool files are safe by default. Python files require `--execute`
+and should only be used with trusted code. The public API may change before
+`1.0.0`.
+
+`mcp-toolsmith` is a small Python-first CLI and library for checking whether tool
+metadata is usable by LLM agents, then compiling those tools into MCP or
+OpenAI-style tool definitions.
+
+It helps catch problems such as vague tool names, missing descriptions,
+oversized schemas, overlapping tools, and prompt-injection-like language inside
+tool metadata.
+
+## Install
+
+```bash
+pip install mcp-toolsmith==0.1.0a1
+```
+
+For local development:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Usage
+
+### Audit JSON tool definitions
+
+JSON tool definitions are safe by default:
+
+```bash
+mcp-toolsmith audit tools.json
+```
+
+Example JSON input:
+
+```json
+{
+  "tools": [
+    {
+      "name": "search_docs",
+      "description": "Search project documentation by natural language query.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Question or topic to search for."
+          },
+          "limit": {
+            "type": "integer",
+            "description": "Maximum number of results to return.",
+            "default": 5
+          }
+        },
+        "required": ["query"]
+      }
+    }
+  ]
+}
+```
+
+Example audit output:
+
+```text
+OK Audited 1 tool(s) from tools.json
+Errors: 0  Warnings: 0
+
+search_docs [mcp] ~55 schema tokens
+  No findings
+```
+
+### Compile tools
+
+Compile to MCP-style tool definitions:
+
+```bash
+mcp-toolsmith compile tools.json --target mcp
+```
+
+Compile to OpenAI-style function definitions:
+
+```bash
+mcp-toolsmith compile tools.json --target openai
+```
+
+### Audit trusted Python files
+
+Python files are executable source code, so `mcp-toolsmith` refuses to import
+them unless you opt in:
+
+```bash
+mcp-toolsmith audit tools.py --execute
+mcp-toolsmith compile tools.py --target mcp --execute
+```
+
+Use `--execute` only for trusted files.
+
+Trusted Python files can contain top-level functions and Pydantic v2 models:
+
+```python
+from pydantic import BaseModel, Field
+
+
+def get_weather(city: str, unit: str = "celsius") -> str:
+    """Get current weather for a city.
+
+    Args:
+        city: City and country, such as Madrid, Spain.
+        unit: Temperature unit to return.
+    """
+    return "sunny"
+
+
+class SearchDocsInput(BaseModel):
+    """Search project documentation by natural language query."""
+
+    query: str = Field(description="Question or topic to search for.")
+    limit: int = Field(default=5, description="Maximum number of results.")
+```
+
+In this alpha, trusted Python discovery includes every public top-level function
+and every public Pydantic model in the file. Decorator-based discovery is planned
+for a later release.
+
+## Python API
+
+```python
+from mcp_toolsmith import audit_file, compile_file
+
+report = audit_file("tools.json")
+report.print()
+
+mcp_tools = compile_file("tools.json", target="mcp")
+openai_tools = compile_file("tools.json", target="openai")
+```
+
+For trusted Python files:
+
+```python
+report = audit_file("tools.py", execute=True)
+mcp_tools = compile_file("tools.py", target="mcp", execute=True)
+```
+
+## Checks
+
+| Check | Why it matters |
+| --- | --- |
+| Vague tool names | Agents may pick the wrong tool when names are generic |
+| Missing descriptions | Tool selection depends heavily on clear descriptions |
+| Missing argument descriptions | Models need argument-level context |
+| Oversized schemas | Large schemas cost tokens and can distract smaller models |
+| Overlapping tools | Similar tools make tool choice unstable |
+| Tool-poisoning language | Tool metadata is part of the prompt surface |
+
+## Roadmap
+
+| Version | Goal |
+| --- | --- |
+| `0.1.0a1` | Safe-by-default CLI, Python/Pydantic discovery behind `--execute`, audit report, MCP/OpenAI compile |
+| `0.2.0` | Decorator-based Python tool discovery |
+| `0.3.0` | OpenAPI input and richer JSON Schema validation |
+| `0.4.0` | Provider compatibility profiles for Anthropic, Gemini, and OpenAI |
+| `0.5.0` | Deterministic schema compaction and rewriting |
+| `1.0.0` | Stable public API and compatibility matrix |
+
+## License
+
+MIT
+

mcp_toolsmith-0.1.0a1/README.md

@@ -0,0 +1,174 @@
+# mcp-toolsmith
+
+Audit and compile Python tool schemas for LLM agents.
+
+**Alpha:** JSON tool files are safe by default. Python files require `--execute`
+and should only be used with trusted code. The public API may change before
+`1.0.0`.
+
+`mcp-toolsmith` is a small Python-first CLI and library for checking whether tool
+metadata is usable by LLM agents, then compiling those tools into MCP or
+OpenAI-style tool definitions.
+
+It helps catch problems such as vague tool names, missing descriptions,
+oversized schemas, overlapping tools, and prompt-injection-like language inside
+tool metadata.
+
+## Install
+
+```bash
+pip install mcp-toolsmith==0.1.0a1
+```
+
+For local development:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Usage
+
+### Audit JSON tool definitions
+
+JSON tool definitions are safe by default:
+
+```bash
+mcp-toolsmith audit tools.json
+```
+
+Example JSON input:
+
+```json
+{
+  "tools": [
+    {
+      "name": "search_docs",
+      "description": "Search project documentation by natural language query.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Question or topic to search for."
+          },
+          "limit": {
+            "type": "integer",
+            "description": "Maximum number of results to return.",
+            "default": 5
+          }
+        },
+        "required": ["query"]
+      }
+    }
+  ]
+}
+```
+
+Example audit output:
+
+```text
+OK Audited 1 tool(s) from tools.json
+Errors: 0  Warnings: 0
+
+search_docs [mcp] ~55 schema tokens
+  No findings
+```
+
+### Compile tools
+
+Compile to MCP-style tool definitions:
+
+```bash
+mcp-toolsmith compile tools.json --target mcp
+```
+
+Compile to OpenAI-style function definitions:
+
+```bash
+mcp-toolsmith compile tools.json --target openai
+```
+
+### Audit trusted Python files
+
+Python files are executable source code, so `mcp-toolsmith` refuses to import
+them unless you opt in:
+
+```bash
+mcp-toolsmith audit tools.py --execute
+mcp-toolsmith compile tools.py --target mcp --execute
+```
+
+Use `--execute` only for trusted files.
+
+Trusted Python files can contain top-level functions and Pydantic v2 models:
+
+```python
+from pydantic import BaseModel, Field
+
+
+def get_weather(city: str, unit: str = "celsius") -> str:
+    """Get current weather for a city.
+
+    Args:
+        city: City and country, such as Madrid, Spain.
+        unit: Temperature unit to return.
+    """
+    return "sunny"
+
+
+class SearchDocsInput(BaseModel):
+    """Search project documentation by natural language query."""
+
+    query: str = Field(description="Question or topic to search for.")
+    limit: int = Field(default=5, description="Maximum number of results.")
+```
+
+In this alpha, trusted Python discovery includes every public top-level function
+and every public Pydantic model in the file. Decorator-based discovery is planned
+for a later release.
+
+## Python API
+
+```python
+from mcp_toolsmith import audit_file, compile_file
+
+report = audit_file("tools.json")
+report.print()
+
+mcp_tools = compile_file("tools.json", target="mcp")
+openai_tools = compile_file("tools.json", target="openai")
+```
+
+For trusted Python files:
+
+```python
+report = audit_file("tools.py", execute=True)
+mcp_tools = compile_file("tools.py", target="mcp", execute=True)
+```
+
+## Checks
+
+| Check | Why it matters |
+| --- | --- |
+| Vague tool names | Agents may pick the wrong tool when names are generic |
+| Missing descriptions | Tool selection depends heavily on clear descriptions |
+| Missing argument descriptions | Models need argument-level context |
+| Oversized schemas | Large schemas cost tokens and can distract smaller models |
+| Overlapping tools | Similar tools make tool choice unstable |
+| Tool-poisoning language | Tool metadata is part of the prompt surface |
+
+## Roadmap
+
+| Version | Goal |
+| --- | --- |
+| `0.1.0a1` | Safe-by-default CLI, Python/Pydantic discovery behind `--execute`, audit report, MCP/OpenAI compile |
+| `0.2.0` | Decorator-based Python tool discovery |
+| `0.3.0` | OpenAPI input and richer JSON Schema validation |
+| `0.4.0` | Provider compatibility profiles for Anthropic, Gemini, and OpenAI |
+| `0.5.0` | Deterministic schema compaction and rewriting |
+| `1.0.0` | Stable public API and compatibility matrix |
+
+## License
+
+MIT
+

mcp_toolsmith-0.1.0a1/docs/release.md

@@ -0,0 +1,51 @@
+# Release
+
+Maintainer notes for publishing `mcp-toolsmith`.
+
+## Checklist
+
+Use a clean working tree:
+
+```bash
+git status --short
+```
+
+Remove local build outputs:
+
+```bash
+rm -rf dist build *.egg-info
+```
+
+Run checks:
+
+```bash
+pytest
+ruff check .
+python -m build
+twine check dist/*
+```
+
+Publish to TestPyPI first:
+
+```bash
+twine upload --repository testpypi dist/*
+```
+
+Then test installation in a clean virtual environment:
+
+```bash
+python -m venv .test-venv
+.test-venv\Scripts\activate
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple mcp-toolsmith==0.1.0a1
+mcp-toolsmith --help
+```
+
+If TestPyPI works, publish the same artifacts to PyPI:
+
+```bash
+twine upload dist/*
+```
+
+Do not commit `dist/`, `build/`, caches, virtual environments, or source
+archives containing `.git/`.
+

mcp_toolsmith-0.1.0a1/pyproject.toml

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-toolsmith"
+version = "0.1.0a1"
+description = "Audit and compile Python tool schemas for LLM agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Shayan Mousavinia" }
+]
+keywords = [
+  "mcp",
+  "llm",
+  "agents",
+  "tool-calling",
+  "json-schema",
+  "pydantic"
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+  "jsonschema>=4.22",
+  "pydantic>=2.7",
+  "rich>=13.7",
+  "typer>=0.12"
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "editables>=0.5",
+  "mypy>=1.10,<1.19",
+  "pytest>=8.0",
+  "ruff>=0.5",
+  "twine>=5.0"
+]
+
+[project.urls]
+Repository = "https://github.com/ShAmoNiA/mcp-toolsmith"
+Issues = "https://github.com/ShAmoNiA/mcp-toolsmith/issues"
+
+[project.scripts]
+mcp-toolsmith = "mcp_toolsmith.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_toolsmith"]
+
+[tool.hatch.build]
+exclude = [
+  "/.git",
+  "/.venv",
+  "/build",
+  "/dist",
+  "/dist_*",
+  "/__pycache__",
+  "/.pytest_cache",
+  "/.ruff_cache",
+  "/.mypy_cache"
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

mcp_toolsmith-0.1.0a1/src/mcp_toolsmith/__init__.py

@@ -0,0 +1,22 @@
+"""Audit and compile Python tool schemas for LLM agents."""
+
+from mcp_toolsmith.auditor import audit_file, audit_tool, audit_tools
+from mcp_toolsmith.compiler import compile_file, compile_tool, compile_tools
+from mcp_toolsmith.introspection import UnsafePythonExecutionError
+from mcp_toolsmith.models import AuditReport, Finding, ToolAudit, ToolSchema
+
+__all__ = [
+    "AuditReport",
+    "Finding",
+    "ToolAudit",
+    "ToolSchema",
+    "UnsafePythonExecutionError",
+    "audit_file",
+    "audit_tool",
+    "audit_tools",
+    "compile_file",
+    "compile_tool",
+    "compile_tools",
+]
+
+__version__ = "0.1.0a1"