bytestay-specwise-mcp 0.2.2__tar.gz

bytestay_specwise_mcp-0.2.2/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: pytest · ruff (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - name: Install
+        run: |
+          uv venv -p ${{ matrix.python }} .venv
+          uv pip install --python .venv/bin/python -e ".[dev]"
+      - name: Tests (no network, 100% coverage)
+        run: .venv/bin/pytest
+      - name: Lint
+        run: .venv/bin/ruff check src tests scripts
+      - name: Build
+        run: uv build

bytestay_specwise_mcp-0.2.2/.github/workflows/mcp-registry.yml

@@ -0,0 +1,42 @@
+name: MCP registry
+
+# Publishes server.json to the official MCP registry (registry.modelcontextprotocol.io).
+# GitHub OIDC proves the run belongs to the bytestay org, which the interactive
+# login can't do for an org namespace. No secret is stored.
+# Called by release.yml after the PyPI publish, or run by hand.
+on:
+  workflow_call:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    env:
+      MCP_PUBLISHER_VERSION: v1.8.7
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+      - name: Download and verify mcp-publisher
+        run: |
+          set -euo pipefail
+          archive="mcp-publisher_linux_amd64.tar.gz"
+          base_url="https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}"
+          curl --fail --location --silent --show-error --output "$archive" "$base_url/$archive"
+          curl --fail --location --silent --show-error --output "$archive.sigstore.json" "$base_url/$archive.sigstore.json"
+          cosign verify-blob --bundle "$archive.sigstore.json" \
+            --certificate-identity "https://github.com/modelcontextprotocol/registry/.github/workflows/release.yml@refs/tags/${MCP_PUBLISHER_VERSION}" \
+            --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+            "$archive"
+          tar xzf "$archive" mcp-publisher
+      - name: Validate server.json
+        run: ./mcp-publisher validate
+      - name: Authenticate to the MCP registry
+        run: ./mcp-publisher login github-oidc
+      - name: Publish
+        run: ./mcp-publisher publish

bytestay_specwise_mcp-0.2.2/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: publish
+
+# ByteStay copy only (marca/rebrand overlay): manual PyPI publish from a tag, with Trusted Publishing.
+# Push a tag (git tag bytestay-specwise-mcp-v0.2.2 && git push origin bytestay-specwise-mcp-v0.2.2), or run it by hand on a tag.
+on:
+  push:
+    tags: ["bytestay-specwise-mcp-v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - name: Check the tag matches the package version
+        run: |
+          version="$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)"
+          [ "${GITHUB_REF_NAME##*-v}" = "$version" ] || { echo "::error::tag $GITHUB_REF_NAME != version $version"; exit 1; }
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

bytestay_specwise_mcp-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+# release-please opens a release PR from Conventional Commits; merging it creates the GitHub release,
+# then the package is published to PyPI with Trusted Publishing (no token stored anywhere).
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+    steps:
+      - id: release
+        uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071 # v4
+        with:
+          # Falls back to GITHUB_TOKEN; needs "Allow GitHub Actions to create and approve pull requests".
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN || github.token }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish:
+    needs: release-please
+    if: needs.release-please.outputs.release_created == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

bytestay_specwise_mcp-0.2.2/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.coverage
+dist/
+*.egg-info/
+.DS_Store

bytestay_specwise_mcp-0.2.2/.release-please-manifest.json

@@ -0,0 +1 @@
+{".":"0.2.2"}

bytestay_specwise_mcp-0.2.2/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## [0.2.2](https://github.com/hybridforgelab/specwise-mcp/compare/hybridforgelab-specwise-mcp-v0.2.1...hybridforgelab-specwise-mcp-v0.2.2) (2026-11-03)
+
+
+### Bug Fixes
+
+* link the PyPI page to the GitHub repo ([#11](https://github.com/hybridforgelab/specwise-mcp/issues/11)) ([1dbf864](https://github.com/hybridforgelab/specwise-mcp/commit/1dbf86421cefd3d0b5fb8456fc7347c40f8b52cc))
+
+
+### Documentation
+
+* M8ven Trust Index badge ([#9](https://github.com/hybridforgelab/specwise-mcp/issues/9)) ([16ec6c2](https://github.com/hybridforgelab/specwise-mcp/commit/16ec6c247e84a5a92d9a40eeeff9ed8d0dcc6b56))
+
+## [0.2.1](https://github.com/hybridforgelab/specwise-mcp/compare/hybridforgelab-specwise-mcp-v0.2.0...hybridforgelab-specwise-mcp-v0.2.1) (2026-11-03)
+
+
+### Bug Fixes
+
+* declare all four tool hints ([#7](https://github.com/hybridforgelab/specwise-mcp/issues/7)) ([887b3cc](https://github.com/hybridforgelab/specwise-mcp/commit/887b3cc836d8cb215eef39a36521f92de3dd6094))
+
+## [0.2.0](https://github.com/hybridforgelab/specwise-mcp/compare/hybridforgelab-specwise-mcp-v0.1.0...hybridforgelab-specwise-mcp-v0.2.0) (2026-11-02)
+
+
+### Features
+
+* list the server in the official MCP registry ([#3](https://github.com/hybridforgelab/specwise-mcp/issues/3)) ([6ae6843](https://github.com/hybridforgelab/specwise-mcp/commit/6ae684387292bf14756d8503b182154054aed9d1))
+
+## 0.1.0 (2026-10-30)
+
+
+### Features
+
+* specwise MCP server ([06a23c1](https://github.com/hybridforgelab/specwise-mcp/commit/06a23c10b5b7f0bee9f72b93bbe4d00dae6cc9fc))

bytestay_specwise_mcp-0.2.2/LICENSE

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

bytestay_specwise_mcp-0.2.2/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.5
+Name: bytestay-specwise-mcp
+Version: 0.2.2
+Summary: OpenAPI validation and breaking-change diffs (also against a git ref) and JSON Schema validation for coding agents. Bring your own RapidAPI or api.market key.
+Project-URL: Homepage, https://specwise.bytestay.pt
+Project-URL: Repository, https://github.com/bytestay/specwise-mcp
+Project-URL: Issues, https://github.com/bytestay/specwise-mcp/issues
+Project-URL: Changelog, https://github.com/bytestay/specwise-mcp/blob/main/CHANGELOG.md
+Author-email: ByteStay <hello@bytestay.pt>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.3
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Specwise MCP server
+
+<!-- mcp-name: io.github.bytestay/specwise-mcp -->
+
+[![M8ven Score](https://m8ven.ai/badge/mcp/hybridforgelab/specwise-mcp?variant=verified)](https://m8ven.ai/mcp/hybridforgelab/specwise-mcp?s=readme)
+[![CI](https://github.com/bytestay/specwise-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bytestay/specwise-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/bytestay-specwise-mcp)](https://pypi.org/project/bytestay-specwise-mcp/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/bytestay-specwise-mcp/)
+[![License: MIT](https://img.shields.io/github/license/bytestay/specwise-mcp)](LICENSE)
+
+Let your coding agent check an API contract: validate an OpenAPI document, find the breaking changes between two versions (also against git), and validate JSON Schemas and data.
+
+The server is open source (MIT). It calls the [Specwise API](https://specwise.bytestay.pt), which is paid, with a free plan.
+
+- You use **your own key, from RapidAPI or api.market**.
+- Every tool call is one request on your plan.
+- The free Basic plan has 15 requests a month, with a hard limit, so it never runs up a bill.
+
+## 1. Get a key
+
+| marketplace | |
+|---|---|
+| RapidAPI | [plans](https://rapidapi.com/hybrid-forge-lab-hybrid-forge-lab-default/api/specwise-openapi-validator-and-diff-api/pricing) |
+| api.market | [store](https://api.market/store/hybrid-forge-lab/specwise) |
+
+## 2. Add the server to your MCP client
+
+The server runs locally over stdio with [uv](https://docs.astral.sh/uv/). Put your key in its environment.
+
+**JSON configuration** (Claude Desktop, Cursor, VS Code and most clients):
+
+```json
+{
+  "mcpServers": {
+    "specwise": {
+      "command": "uvx",
+      "args": ["--from", "bytestay-specwise-mcp", "specwise-mcp"],
+      "env": { "RAPIDAPI_KEY": "your-rapidapi-key" }
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add specwise --env RAPIDAPI_KEY=your-rapidapi-key -- uvx --from bytestay-specwise-mcp specwise-mcp
+```
+
+### Environment
+
+| variable | meaning |
+|---|---|
+| `RAPIDAPI_KEY` | your RapidAPI key |
+| `API_MARKET_KEY` | your api.market key, used when `RAPIDAPI_KEY` is not set |
+| `HFL_MARKETPLACE` | `rapidapi` or `apimarket`, when both keys are set |
+
+Without a key the server still starts. The first tool call then explains where to get one.
+
+Also listed on Glama:
+
+[![specwise-mcp on Glama](https://glama.ai/mcp/servers/hybridforgelab/specwise-mcp/badge)](https://glama.ai/mcp/servers/hybridforgelab/specwise-mcp)
+
+## 3. Tools
+
+| tool | what it does |
+|---|---|
+| `validate_openapi(spec=… \| spec_path=…)` | every error with its JSON Pointer, line and column, plus lint warnings (OpenAPI 3.x and Swagger 2.0) |
+| `diff_openapi(...)` | each change between two OpenAPI 3.x versions is breaking, warning, non-breaking or info, with a semver suggestion |
+| `validate_json_schema(schema=… \| schema_path=…, instance=… \| instance_path=…, draft=None)` | checks the schema against its meta-schema and, if given, the data against the schema |
+
+`diff_openapi` takes the two versions in one of three ways:
+
+- `base` and `revision` as text;
+- `base_path` and `revision_path` as files;
+- `revision_path` with `base_git_ref`. For example, after editing a spec: `revision_path="openapi.yaml", base_git_ref="main"`.
+
+Every tool returns the API's JSON response.
+
+- When the marketplace reports it, `quota_remaining` is added: the requests left on your plan this month.
+- Errors are explained in plain words, with what to do next:
+  - key refused, with the link to subscribe;
+  - quota reached, with the plans;
+  - input the API couldn't process, with the API's reason.
+
+## Privacy
+
+- Local files are read only when a tool is given their path. They are sent to the API for that one request.
+- The API processes inputs in memory and doesn't store them. See the [privacy policy](https://specwise.bytestay.pt/privacy.html).
+- Your key is only sent to the marketplace you chose.
+
+## Limits
+
+- Documents up to about 900 KiB each.
+- External `$ref`s are not fetched. Bundle multi-file specs first (`redocly bundle`).
+- The diff needs OpenAPI 3.x; Swagger 2.0 can be validated, not diffed.
+- The server needs Python 3.10+ (uv installs it for you).
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+.venv/bin/pytest            # unit tests, no network; 100% coverage required
+.venv/bin/ruff check src tests scripts
+```
+
+`scripts/e2e_stdio.py specwise` runs the server over stdio, as a client would, and calls its tools against the real API. It needs `RAPIDAPI_KEY` or `API_MARKET_KEY`.
+
+## Licence
+
+MIT. Specwise itself is a paid API with a free plan, run by [ByteStay](https://bytestay.pt).

bytestay_specwise_mcp-0.2.2/README.md

@@ -0,0 +1,111 @@
+# Specwise MCP server
+
+<!-- mcp-name: io.github.bytestay/specwise-mcp -->
+
+[![M8ven Score](https://m8ven.ai/badge/mcp/hybridforgelab/specwise-mcp?variant=verified)](https://m8ven.ai/mcp/hybridforgelab/specwise-mcp?s=readme)
+[![CI](https://github.com/bytestay/specwise-mcp/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bytestay/specwise-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/bytestay-specwise-mcp)](https://pypi.org/project/bytestay-specwise-mcp/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/bytestay-specwise-mcp/)
+[![License: MIT](https://img.shields.io/github/license/bytestay/specwise-mcp)](LICENSE)
+
+Let your coding agent check an API contract: validate an OpenAPI document, find the breaking changes between two versions (also against git), and validate JSON Schemas and data.
+
+The server is open source (MIT). It calls the [Specwise API](https://specwise.bytestay.pt), which is paid, with a free plan.
+
+- You use **your own key, from RapidAPI or api.market**.
+- Every tool call is one request on your plan.
+- The free Basic plan has 15 requests a month, with a hard limit, so it never runs up a bill.
+
+## 1. Get a key
+
+| marketplace | |
+|---|---|
+| RapidAPI | [plans](https://rapidapi.com/hybrid-forge-lab-hybrid-forge-lab-default/api/specwise-openapi-validator-and-diff-api/pricing) |
+| api.market | [store](https://api.market/store/hybrid-forge-lab/specwise) |
+
+## 2. Add the server to your MCP client
+
+The server runs locally over stdio with [uv](https://docs.astral.sh/uv/). Put your key in its environment.
+
+**JSON configuration** (Claude Desktop, Cursor, VS Code and most clients):
+
+```json
+{
+  "mcpServers": {
+    "specwise": {
+      "command": "uvx",
+      "args": ["--from", "bytestay-specwise-mcp", "specwise-mcp"],
+      "env": { "RAPIDAPI_KEY": "your-rapidapi-key" }
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add specwise --env RAPIDAPI_KEY=your-rapidapi-key -- uvx --from bytestay-specwise-mcp specwise-mcp
+```
+
+### Environment
+
+| variable | meaning |
+|---|---|
+| `RAPIDAPI_KEY` | your RapidAPI key |
+| `API_MARKET_KEY` | your api.market key, used when `RAPIDAPI_KEY` is not set |
+| `HFL_MARKETPLACE` | `rapidapi` or `apimarket`, when both keys are set |
+
+Without a key the server still starts. The first tool call then explains where to get one.
+
+Also listed on Glama:
+
+[![specwise-mcp on Glama](https://glama.ai/mcp/servers/hybridforgelab/specwise-mcp/badge)](https://glama.ai/mcp/servers/hybridforgelab/specwise-mcp)
+
+## 3. Tools
+
+| tool | what it does |
+|---|---|
+| `validate_openapi(spec=… \| spec_path=…)` | every error with its JSON Pointer, line and column, plus lint warnings (OpenAPI 3.x and Swagger 2.0) |
+| `diff_openapi(...)` | each change between two OpenAPI 3.x versions is breaking, warning, non-breaking or info, with a semver suggestion |
+| `validate_json_schema(schema=… \| schema_path=…, instance=… \| instance_path=…, draft=None)` | checks the schema against its meta-schema and, if given, the data against the schema |
+
+`diff_openapi` takes the two versions in one of three ways:
+
+- `base` and `revision` as text;
+- `base_path` and `revision_path` as files;
+- `revision_path` with `base_git_ref`. For example, after editing a spec: `revision_path="openapi.yaml", base_git_ref="main"`.
+
+Every tool returns the API's JSON response.
+
+- When the marketplace reports it, `quota_remaining` is added: the requests left on your plan this month.
+- Errors are explained in plain words, with what to do next:
+  - key refused, with the link to subscribe;
+  - quota reached, with the plans;
+  - input the API couldn't process, with the API's reason.
+
+## Privacy
+
+- Local files are read only when a tool is given their path. They are sent to the API for that one request.
+- The API processes inputs in memory and doesn't store them. See the [privacy policy](https://specwise.bytestay.pt/privacy.html).
+- Your key is only sent to the marketplace you chose.
+
+## Limits
+
+- Documents up to about 900 KiB each.
+- External `$ref`s are not fetched. Bundle multi-file specs first (`redocly bundle`).
+- The diff needs OpenAPI 3.x; Swagger 2.0 can be validated, not diffed.
+- The server needs Python 3.10+ (uv installs it for you).
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+.venv/bin/pytest            # unit tests, no network; 100% coverage required
+.venv/bin/ruff check src tests scripts
+```
+
+`scripts/e2e_stdio.py specwise` runs the server over stdio, as a client would, and calls its tools against the real API. It needs `RAPIDAPI_KEY` or `API_MARKET_KEY`.
+
+## Licence
+
+MIT. Specwise itself is a paid API with a free plan, run by [ByteStay](https://bytestay.pt).

bytestay_specwise_mcp-0.2.2/glama.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["fredfrazao"]
+}

bytestay_specwise_mcp-0.2.2/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "bytestay-specwise-mcp"
+version = "0.2.2"
+description = "OpenAPI validation and breaking-change diffs (also against a git ref) and JSON Schema validation for coding agents. Bring your own RapidAPI or api.market key."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "ByteStay", email = "hello@bytestay.pt" }]
+dependencies = ["mcp>=2.3,<3", "httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://specwise.bytestay.pt"
+Repository = "https://github.com/bytestay/specwise-mcp"
+Issues = "https://github.com/bytestay/specwise-mcp/issues"
+Changelog = "https://github.com/bytestay/specwise-mcp/blob/main/CHANGELOG.md"
+
+[project.scripts]
+specwise-mcp = "specwise_mcp.server:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "pytest-cov>=5", "ruff>=0.6"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/specwise_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "-q --cov=specwise_mcp --cov-report=term-missing:skip-covered --cov-fail-under=100"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120

bytestay_specwise_mcp-0.2.2/release-please-config.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "python",
+  "packages": {
+    ".": {
+      "package-name": "bytestay-specwise-mcp",
+      "changelog-path": "CHANGELOG.md",
+      "extra-files": [
+        "src/specwise_mcp/__init__.py",
+        {
+          "type": "json",
+          "path": "server.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": "server.json",
+          "jsonpath": "$.packages[0].version"
+        }
+      ]
+    }
+  }
+}

bytestay_specwise_mcp-0.2.2/scripts/e2e_stdio.py

@@ -0,0 +1,66 @@
+"""End-to-end check of the Specwise server over stdio, as an MCP client would run it, against the real API.
+
+    HFL_API_URL=https://specwise-api.bytestay.pt HFL_API_BEARER=... python scripts/e2e_stdio.py specwise
+
+Needs either HFL_API_URL + HFL_API_BEARER (maintainers, no marketplace quota spent) or RAPIDAPI_KEY / API_MARKET_KEY.
+Prints one line per check and exits non-zero on any failure. Never prints a key.
+"""
+import asyncio
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+from mcp import ClientSession
+from mcp.client.stdio import StdioServerParameters, stdio_client
+
+ROOT = Path(__file__).resolve().parent.parent
+FIX = Path.home() / "code/ffrazao/specwise-action/tests/fixtures"
+ENV_KEYS = ("HFL_API_URL", "HFL_API_BEARER", "RAPIDAPI_KEY", "API_MARKET_KEY", "HFL_MARKETPLACE", "PATH", "HOME")
+
+
+def data(result):
+    assert not result.is_error, result.content[0].text if result.content else "error"
+    return json.loads(result.content[0].text)
+
+
+def checks(name, tmp: Path):
+    if name == "specwise":
+        return [
+            ("validate_openapi file", "validate_openapi", {"spec_path": str(FIX / "base.yaml")},
+             lambda d: d["valid"] is True),
+            ("diff_openapi files", "diff_openapi",
+             {"base_path": str(FIX / "base.yaml"), "revision_path": str(FIX / "revision.yaml")},
+             lambda d: d["breaking"] is True and d["summary"]["breaking"] == 3),
+            ("validate_json_schema", "validate_json_schema",
+             {"schema": '{"type": "object", "required": ["a"]}', "instance": "{}"},
+             lambda d: d["valid"] is False and d["error_count"] == 1),
+        ]
+    raise SystemExit(f"unknown server {name}")
+
+
+async def main(name):
+    env = {k: os.environ[k] for k in ENV_KEYS if k in os.environ}
+    params = StdioServerParameters(command=str(ROOT / ".venv/bin/python"), args=["-m", "specwise_mcp.server"], env=env)
+    failures = 0
+    with tempfile.TemporaryDirectory() as tmp:
+        async with stdio_client(params) as (read, write), ClientSession(read, write) as session:
+            await session.initialize()
+            tools = sorted(t.name for t in (await session.list_tools()).tools)
+            print(f"{name}: tools {tools}")
+            for label, tool, args, ok in checks(name, Path(tmp)):
+                try:
+                    d = data(await session.call_tool(tool, args))
+                    good = ok(d)
+                    extra = f" quota_remaining={d['quota_remaining']}" if "quota_remaining" in d else ""
+                    print(f"  {'PASS' if good else 'FAIL'} {label}{extra}")
+                except Exception as exc:  # noqa: BLE001 - report and continue
+                    good = False
+                    print(f"  FAIL {label}: {str(exc)[:200]}")
+                failures += not good
+    return failures
+
+
+if __name__ == "__main__":
+    sys.exit(1 if asyncio.run(main(sys.argv[1])) else 0)

bytestay_specwise_mcp-0.2.2/server.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.bytestay/specwise-mcp",
+  "description": "OpenAPI and JSON Schema validation and OpenAPI breaking-change diffs for AI agents.",
+  "repository": {
+    "url": "https://github.com/bytestay/specwise-mcp",
+    "source": "github",
+    "id": "1445856363"
+  },
+  "websiteUrl": "https://specwise.bytestay.pt/integration.html#mcp-server",
+  "version": "0.2.2",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "bytestay-specwise-mcp",
+      "version": "0.2.2",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "RAPIDAPI_KEY",
+          "description": "Your RapidAPI key",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        },
+        {
+          "name": "API_MARKET_KEY",
+          "description": "Your api.market key, used when RAPIDAPI_KEY is not set",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        },
+        {
+          "name": "HFL_MARKETPLACE",
+          "description": "rapidapi or apimarket, when both keys are set",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "string",
+          "choices": [
+            "rapidapi",
+            "apimarket"
+          ]
+        }
+      ]
+    }
+  ]
+}

bytestay_specwise_mcp-0.2.2/src/specwise_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""Specwise MCP server."""
+__version__ = "0.2.2"  # x-release-please-version

bytestay_specwise_mcp-0.2.2/src/specwise_mcp/client.py

@@ -0,0 +1,111 @@
+"""HTTP client: picks the marketplace from the environment and turns API errors into
+messages an agent (and its user) can act on."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+from mcp.server.mcpserver.exceptions import ToolError
+
+from . import __version__
+
+RAPIDAPI_LISTING = "https://rapidapi.com/hybrid-forge-lab-hybrid-forge-lab-default/api/"
+APIMARKET_BASE = "https://prod.api.market/api/v1/hybrid-forge-lab/"
+APIMARKET_STORE = "https://api.market/store/hybrid-forge-lab/"
+USER_AGENT = f"specwise-mcp/{__version__} (+https://specwise.bytestay.pt)"
+TIMEOUT = httpx.Timeout(60.0, connect=10.0)
+
+# Tests swap this for an httpx.MockTransport.
+TRANSPORT: httpx.AsyncBaseTransport | None = None
+
+
+@dataclass(frozen=True)
+class Product:
+    slug: str
+    name: str
+    rapidapi: str  # RapidAPI listing slug; the host is "<slug>.p.rapidapi.com"
+    apimarket: bool  # sold on api.market too
+
+    @property
+    def rapidapi_host(self) -> str:
+        return f"{self.rapidapi}.p.rapidapi.com"
+
+    @property
+    def plans(self) -> str:
+        return RAPIDAPI_LISTING + self.rapidapi + "/pricing"
+
+
+PRODUCTS = {
+    "specwise": Product("specwise", "Specwise", "specwise-openapi-validator-and-diff-api", apimarket=True),
+}
+
+
+@dataclass(frozen=True)
+class Target:
+    base: str
+    headers: dict[str, str]
+    market: str  # "rapidapi", "apimarket" or "direct"
+
+
+def target(product: Product, env: dict[str, str] | None = None) -> Target:
+    """Where to send requests, from the environment. Read on every call, so the server starts without a key and
+    the first tool call explains how to get one."""
+    env = dict(os.environ if env is None else env)
+    # Maintainers only: call our own host directly with an internal bearer key.
+    if env.get("HFL_API_URL") and env.get("HFL_API_BEARER"):
+        return Target(env["HFL_API_URL"].rstrip("/"), {"Authorization": f"Bearer {env['HFL_API_BEARER']}"}, "direct")
+    rapid, market = env.get("RAPIDAPI_KEY", ""), env.get("API_MARKET_KEY", "")
+    choice = env.get("HFL_MARKETPLACE", "").lower()
+    if choice == "apimarket" or (market and not rapid and choice != "rapidapi"):
+        if not market:
+            raise ToolError("HFL_MARKETPLACE is apimarket but API_MARKET_KEY is not set.")
+        return Target(APIMARKET_BASE + product.slug, {"x-api-market-key": market}, "apimarket")
+    if not rapid:
+        where = f" or API_MARKET_KEY ({APIMARKET_STORE}{product.slug})" if product.apimarket else ""
+        raise ToolError(f"No API key. Set RAPIDAPI_KEY (free Basic plan: {product.plans}){where} in this MCP "
+                        "server's environment, then restart it.")
+    return Target(f"https://{product.rapidapi_host}",
+                  {"X-RapidAPI-Key": rapid, "X-RapidAPI-Host": product.rapidapi_host}, "rapidapi")
+
+
+def _detail(response: httpx.Response) -> str:
+    try:
+        body = response.json()
+    except ValueError:
+        return response.text[:300]
+    if isinstance(body, dict):
+        detail = body.get("detail", body.get("message", body))
+        return detail if isinstance(detail, str) else str(detail)[:500]
+    return str(body)[:300]
+
+
+async def call(product: Product, method: str, path: str, *, json: Any = None, params: dict | None = None,
+               files: dict | None = None, data: dict | None = None) -> dict:
+    """One API request. Returns the JSON body, plus `quota_remaining` when the marketplace reports it."""
+    t = target(product)
+    url = t.base + path
+    headers = {"User-Agent": USER_AGENT, **t.headers}
+    try:
+        async with httpx.AsyncClient(timeout=TIMEOUT, transport=TRANSPORT) as client:
+            r = await client.request(method, url, headers=headers, json=json, params=params, files=files, data=data)
+    except httpx.HTTPError as exc:
+        raise ToolError(f"The {product.name} API could not be reached ({type(exc).__name__}). Try again later.")
+    if r.status_code in (401, 403):
+        how = f"{APIMARKET_STORE}{product.slug}" if t.market == "apimarket" else product.plans
+        raise ToolError(f"The {product.name} API refused the key (HTTP {r.status_code}: {_detail(r)}). "
+                        f"Check the key and the subscription: {how}")
+    if r.status_code == 429:
+        raise ToolError(f"{product.name} rate or monthly quota limit reached ({_detail(r)}). Plans: {product.plans}")
+    if r.status_code == 413:
+        raise ToolError(f"The input is too large for {product.name} ({_detail(r)}).")
+    if r.status_code == 422:
+        raise ToolError(f"{product.name} could not process the input: {_detail(r)}")
+    if r.status_code >= 400:
+        raise ToolError(f"The {product.name} API answered HTTP {r.status_code}: {_detail(r)}. Try again later.")
+    body = r.json()
+    quota = r.headers.get("x-ratelimit-requests-remaining")
+    if quota is not None and isinstance(body, dict):
+        body["quota_remaining"] = int(quota) if quota.isdigit() else quota
+    return body

bytestay_specwise_mcp-0.2.2/src/specwise_mcp/files.py

@@ -0,0 +1,41 @@
+"""Reading local files and git revisions for tools that accept a path instead of the content."""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from mcp.server.mcpserver.exceptions import ToolError
+
+
+def resolve(path: str) -> Path:
+    p = Path(path).expanduser()
+    if not p.is_file():
+        raise ToolError(f"No such file: {p} (relative paths start from {Path.cwd()}).")
+    return p
+
+
+def read_text(path: str, max_bytes: int) -> str:
+    p = resolve(path)
+    size = p.stat().st_size
+    if size > max_bytes:
+        raise ToolError(f"{p} is {size:,} bytes; the limit is {max_bytes:,}.")
+    try:
+        return p.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        raise ToolError(f"{p} is not UTF-8 text.")
+
+def git_show(path: str, ref: str) -> str:
+    """The file as it is at `ref` (a branch, tag or commit) in the git repository that contains it."""
+    p = resolve(path).resolve()
+
+    def run(*args: str) -> subprocess.CompletedProcess:
+        return subprocess.run(["git", "-C", str(p.parent), *args], check=False, capture_output=True, text=True)
+
+    top = run("rev-parse", "--show-toplevel")
+    if top.returncode != 0:
+        raise ToolError(f"{p} is not in a git repository.")
+    rel = p.relative_to(Path(top.stdout.strip()).resolve()).as_posix()
+    shown = run("show", f"{ref}:{rel}")
+    if shown.returncode != 0:
+        raise ToolError(f"Could not read {rel} at {ref!r}: {shown.stderr.strip()[:200]}")
+    return shown.stdout

bytestay_specwise_mcp-0.2.2/src/specwise_mcp/server.py

@@ -0,0 +1,106 @@
+"""Specwise MCP server: OpenAPI and JSON Schema validation, and OpenAPI breaking-change diffs."""
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from . import files
+from .client import PRODUCTS, call
+
+PRODUCT = PRODUCTS["specwise"]
+MAX_FILE = 900 * 1024  # two documents must fit in the API's 2 MB request
+
+server = MCPServer(
+    "specwise",
+    title="Specwise: OpenAPI validation and breaking changes",
+    instructions=(
+        "Validate an OpenAPI (3.x or Swagger 2.0) document and get every error with its JSON Pointer, line and "
+        "column. Compare two OpenAPI 3.x versions and get each change classified as breaking, warning, "
+        "non-breaking or info, with a semver suggestion; use it after editing a spec, against the git version. "
+        "Validate JSON Schemas and data. Documents are processed in memory and not stored, and external $refs are "
+        "never fetched. Each call is one request on the user's Specwise plan."
+    ),
+    website_url="https://specwise.bytestay.pt",
+)
+
+READ_ONLY = ToolAnnotations(read_only_hint=True, destructive_hint=False, idempotent_hint=True, open_world_hint=True)
+
+
+# MCP clients may send JSON documents as objects, and the SDK parses JSON-looking strings into objects too.
+# The API takes both: text keeps line numbers, objects are validated as they are.
+Doc = str | dict | list | bool | int | float
+
+
+def _one(value: Doc | None, path: str | None, what: str) -> Doc:
+    given = value is not None and value != ""
+    if given == bool(path):
+        raise ToolError(f"Give exactly one of {what} or {what}_path.")
+    return value if given else files.read_text(path, MAX_FILE)
+
+
+@server.tool(annotations=READ_ONLY)
+async def validate_openapi(
+    spec: Annotated[Doc | None, Field(description="The document as YAML or JSON text (or a JSON object).")] = None,
+    spec_path: Annotated[str | None, Field(description="A local file instead of `spec`.")] = None,
+) -> dict:
+    """Validate an OpenAPI 3.0/3.1/3.2 or Swagger 2.0 document. Returns every error (not just the first) with its
+    JSON Pointer, line and column, plus lint warnings."""
+    return await call(PRODUCT, "POST", "/v1/openapi/validate", json={"spec": _one(spec, spec_path, "spec")})
+
+
+@server.tool(annotations=READ_ONLY)
+async def diff_openapi(
+    base: Annotated[Doc | None, Field(description="The old version, as YAML or JSON text (or a JSON object).")] = None,
+    base_path: Annotated[str | None, Field(description="The old version as a local file.")] = None,
+    revision: Annotated[Doc | None, Field(description="The new version, as YAML or JSON text (or a JSON object).")] = None,
+    revision_path: Annotated[str | None, Field(description="The new version as a local file.")] = None,
+    base_git_ref: Annotated[str | None, Field(
+        description="Use revision_path as it is at this git ref (e.g. main, HEAD) as the base.")] = None,
+) -> dict:
+    """Compare two OpenAPI 3.x documents. Each change is breaking, warning, non-breaking or info; `breaking` says
+    whether any is breaking, and `semver` suggests the version bump.
+
+    Typical use after editing a spec: revision_path="openapi.yaml", base_git_ref="main"."""
+    new = _one(revision, revision_path, "revision")
+    if base_git_ref:
+        if base or base_path:
+            raise ToolError("Give base_git_ref or base/base_path, not both.")
+        if not revision_path:
+            raise ToolError("base_git_ref needs revision_path.")
+        old = files.git_show(revision_path, base_git_ref)
+    else:
+        old = _one(base, base_path, "base")
+    return await call(PRODUCT, "POST", "/v1/openapi/diff", json={"base": old, "revision": new})
+
+
+@server.tool(annotations=READ_ONLY)
+async def validate_json_schema(
+    schema: Annotated[Doc | None, Field(description="The JSON Schema, as JSON or YAML text (or a JSON object).")] = None,
+    schema_path: Annotated[str | None, Field(description="A local file instead of `schema`.")] = None,
+    instance: Annotated[Any, Field(description="Data to validate: JSON or YAML text, or the value itself. Optional.")] = None,
+    instance_path: Annotated[str | None, Field(description="Data to validate, from a local file.")] = None,
+    draft: Annotated[Literal["4", "6", "7", "2019-09", "2020-12"] | None,
+                     Field(description="Force a draft; by default from $schema, else 2020-12.")] = None,
+) -> dict:
+    """Check a JSON Schema against its meta-schema and, if given, validate data against it. Every error has the
+    instance path, the schema path and, for text input, the line."""
+    body: dict = {"schema": _one(schema, schema_path, "schema")}
+    if instance is not None or instance_path:
+        value = _one(instance, instance_path, "instance")
+        body["instance"] = value
+        # Text is parsed as YAML (a superset of JSON) and gives line numbers; anything else is the value itself.
+        body["instance_format"] = "yaml" if isinstance(value, str) else "value"
+    if draft:
+        body["draft"] = draft
+    return await call(PRODUCT, "POST", "/v1/jsonschema/validate", json=body)
+
+
+def main() -> None:  # pragma: no cover - stdio entry point
+    server.run("stdio")
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

bytestay_specwise_mcp-0.2.2/tests/conftest.py

@@ -0,0 +1,38 @@
+import json
+
+import httpx
+import pytest
+
+from specwise_mcp import client
+
+
+class Recorder:
+    """Answers every request with the next queued response and keeps what was sent."""
+
+    def __init__(self):
+        self.requests: list[httpx.Request] = []
+        self.responses: list[httpx.Response] = []
+
+    def queue(self, status=200, body=None, headers=None):
+        self.responses.append(httpx.Response(status, json=body if body is not None else {}, headers=headers or {}))
+
+    def __call__(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        return self.responses.pop(0) if self.responses else httpx.Response(200, json={})
+
+    @property
+    def last(self) -> httpx.Request:
+        return self.requests[-1]
+
+    def last_json(self):
+        return json.loads(self.last.content)
+
+
+@pytest.fixture
+def api(monkeypatch):
+    rec = Recorder()
+    monkeypatch.setattr(client, "TRANSPORT", httpx.MockTransport(rec))
+    for name in ("RAPIDAPI_KEY", "API_MARKET_KEY", "HFL_MARKETPLACE", "HFL_API_URL", "HFL_API_BEARER"):
+        monkeypatch.delenv(name, raising=False)
+    monkeypatch.setenv("RAPIDAPI_KEY", "rk")
+    return rec

bytestay_specwise_mcp-0.2.2/tests/test_client.py

@@ -0,0 +1,99 @@
+import httpx
+import pytest
+from mcp.server.mcpserver.exceptions import ToolError
+
+from specwise_mcp import client
+from specwise_mcp.client import PRODUCTS, call, target
+
+P = PRODUCTS["specwise"]
+HOST = "specwise-openapi-validator-and-diff-api.p.rapidapi.com"
+
+
+def test_rapidapi_by_default():
+    t = target(P, {"RAPIDAPI_KEY": "rk"})
+    assert t.market == "rapidapi" and t.base == f"https://{HOST}"
+    assert t.headers == {"X-RapidAPI-Key": "rk", "X-RapidAPI-Host": HOST}
+
+
+def test_direct_for_maintainers():
+    t = target(P, {"HFL_API_URL": "https://api.example/", "HFL_API_BEARER": "b", "RAPIDAPI_KEY": "rk"})
+    assert t.market == "direct" and t.base == "https://api.example" and t.headers == {"Authorization": "Bearer b"}
+
+
+def test_env_is_read_from_os_by_default(monkeypatch):
+    monkeypatch.setenv("RAPIDAPI_KEY", "from-os")
+    monkeypatch.delenv("HFL_API_URL", raising=False)
+    monkeypatch.delenv("HFL_MARKETPLACE", raising=False)
+    assert target(P).headers["X-RapidAPI-Key"] == "from-os"
+
+
+def test_apimarket_when_only_its_key_is_set_or_chosen():
+    t = target(P, {"API_MARKET_KEY": "mk"})
+    assert t.market == "apimarket" and t.base == "https://prod.api.market/api/v1/hybrid-forge-lab/specwise"
+    assert t.headers == {"x-api-market-key": "mk"}
+    assert target(P, {"RAPIDAPI_KEY": "rk", "API_MARKET_KEY": "mk", "HFL_MARKETPLACE": "apimarket"}).market == "apimarket"
+    assert target(P, {"RAPIDAPI_KEY": "rk", "API_MARKET_KEY": "mk"}).market == "rapidapi"
+    assert target(P, {"RAPIDAPI_KEY": "rk", "API_MARKET_KEY": "mk", "HFL_MARKETPLACE": "rapidapi"}).market == "rapidapi"
+
+
+def test_key_errors_explain_what_to_do():
+    with pytest.raises(ToolError, match="No API key. Set RAPIDAPI_KEY .*api.market"):
+        target(P, {})
+    with pytest.raises(ToolError, match="API_MARKET_KEY is not set"):
+        target(P, {"RAPIDAPI_KEY": "rk", "HFL_MARKETPLACE": "apimarket"})
+
+
+async def test_apimarket_refusal_points_to_the_store(api, monkeypatch):
+    monkeypatch.delenv("RAPIDAPI_KEY")
+    monkeypatch.setenv("API_MARKET_KEY", "mk")
+    api.queue(403, {"message": "no"})
+    with pytest.raises(ToolError, match="api.market/store/hybrid-forge-lab/specwise"):
+        await call(P, "GET", "/x")
+
+
+async def test_success_adds_quota_and_user_agent(api):
+    api.queue(200, {"status": "ok"}, {"x-ratelimit-requests-remaining": "12"})
+    r = await call(P, "POST", "/v1/x", json={"a": 1})
+    assert r == {"status": "ok", "quota_remaining": 12}
+    assert api.last.headers["user-agent"].startswith("specwise-mcp/")
+    api.queue(200, {"a": 1}, {"x-ratelimit-requests-remaining": "n/a"})
+    assert (await call(P, "GET", "/x"))["quota_remaining"] == "n/a"
+    api.queue(200, [1, 2], {"x-ratelimit-requests-remaining": "3"})
+    assert await call(P, "GET", "/x") == [1, 2]
+
+
+@pytest.mark.parametrize("status,body,match", [
+    (401, {"message": "Invalid API key"}, "refused the key .*401: Invalid API key.*specwise-openapi-validator-and-diff-api/pricing"),
+    (403, {"message": "You are not subscribed"}, "refused the key"),
+    (429, {"message": "quota"}, "quota limit reached"),
+    (413, {"detail": "body too large"}, "too large"),
+    (422, {"detail": [{"loc": ["x"], "msg": "bad"}]}, "could not process the input: .*bad"),
+    (500, {"detail": "boom"}, "HTTP 500: boom"),
+])
+async def test_errors(api, status, body, match):
+    api.queue(status, body)
+    with pytest.raises(ToolError, match=match):
+        await call(P, "GET", "/x")
+
+
+async def test_non_json_and_non_dict_error_bodies(monkeypatch):
+    def handler(request):
+        return httpx.Response(502, text="<html>bad gateway</html>") if "a" in request.url.path \
+            else httpx.Response(503, json=["down"])
+    monkeypatch.setattr(client, "TRANSPORT", httpx.MockTransport(handler))
+    monkeypatch.setenv("RAPIDAPI_KEY", "rk")
+    monkeypatch.delenv("HFL_API_URL", raising=False)
+    with pytest.raises(ToolError, match="502: <html>bad gateway"):
+        await call(P, "GET", "/a")
+    with pytest.raises(ToolError, match=r"503: \['down'\]"):
+        await call(P, "GET", "/b")
+
+
+async def test_network_failure(monkeypatch):
+    def handler(request):
+        raise httpx.ConnectTimeout("slow")
+    monkeypatch.setattr(client, "TRANSPORT", httpx.MockTransport(handler))
+    monkeypatch.setenv("RAPIDAPI_KEY", "rk")
+    monkeypatch.delenv("HFL_API_URL", raising=False)
+    with pytest.raises(ToolError, match="could not be reached \\(ConnectTimeout\\)"):
+        await call(P, "GET", "/x")

bytestay_specwise_mcp-0.2.2/tests/test_server.py

@@ -0,0 +1,106 @@
+import subprocess
+
+import pytest
+from mcp.server.mcpserver.exceptions import ToolError
+
+from specwise_mcp import files
+from specwise_mcp import server as specwise
+
+SPEC_V1 = "openapi: 3.0.3\ninfo: {title: t, version: '1'}\npaths: {}\n"
+SPEC_V2 = "openapi: 3.0.3\ninfo: {title: t, version: '2'}\npaths: {}\n"
+
+
+async def test_server_lists_its_tools():
+    listed = await specwise.server.list_tools()
+    assert {t.name for t in listed} == {"validate_openapi", "diff_openapi", "validate_json_schema"}
+    for t in listed:
+        assert t.description
+        assert t.annotations.read_only_hint is True and t.annotations.destructive_hint is False
+        assert t.annotations.idempotent_hint is True and t.annotations.open_world_hint is True
+
+
+async def test_validate_openapi(api, tmp_path):
+    await specwise.validate_openapi(spec=SPEC_V1)
+    assert api.last.url.path == "/v1/openapi/validate" and api.last_json() == {"spec": SPEC_V1}
+    f = tmp_path / "openapi.yaml"
+    f.write_text(SPEC_V2)
+    await specwise.validate_openapi(spec_path=str(f))
+    assert api.last_json() == {"spec": SPEC_V2}
+    with pytest.raises(ToolError, match="exactly one of spec or spec_path"):
+        await specwise.validate_openapi()
+
+
+async def test_diff_openapi_text_and_files(api, tmp_path):
+    await specwise.diff_openapi(base=SPEC_V1, revision=SPEC_V2)
+    assert api.last.url.path == "/v1/openapi/diff" and api.last_json() == {"base": SPEC_V1, "revision": SPEC_V2}
+    a, b = tmp_path / "a.yaml", tmp_path / "b.yaml"
+    a.write_text(SPEC_V1)
+    b.write_text(SPEC_V2)
+    await specwise.diff_openapi(base_path=str(a), revision_path=str(b))
+    assert api.last_json() == {"base": SPEC_V1, "revision": SPEC_V2}
+
+
+def git(repo, *args):
+    subprocess.run(["git", "-C", str(repo), "-c", "user.email=t@t", "-c", "user.name=t", *args], check=True,
+                   capture_output=True)
+
+
+async def test_diff_against_a_git_ref(api, tmp_path):
+    repo = tmp_path / "repo"
+    (repo / "api").mkdir(parents=True)
+    git(repo, "init", "-q", "-b", "main")
+    spec = repo / "api" / "openapi.yaml"
+    spec.write_text(SPEC_V1)
+    git(repo, "add", "-A")
+    git(repo, "commit", "-qm", "v1")
+    spec.write_text(SPEC_V2)  # uncommitted edit
+    await specwise.diff_openapi(revision_path=str(spec), base_git_ref="HEAD")
+    assert api.last_json() == {"base": SPEC_V1, "revision": SPEC_V2}
+    with pytest.raises(ToolError, match="Could not read api/openapi.yaml at 'nope'"):
+        await specwise.diff_openapi(revision_path=str(spec), base_git_ref="nope")
+    with pytest.raises(ToolError, match="not both"):
+        await specwise.diff_openapi(base=SPEC_V1, revision_path=str(spec), base_git_ref="HEAD")
+    with pytest.raises(ToolError, match="needs revision_path"):
+        await specwise.diff_openapi(revision=SPEC_V2, base_git_ref="HEAD")
+    outside = tmp_path / "outside.yaml"
+    outside.write_text(SPEC_V2)
+    with pytest.raises(ToolError, match="not in a git repository"):
+        await specwise.diff_openapi(revision_path=str(outside), base_git_ref="HEAD")
+
+
+async def test_validate_json_schema(api, tmp_path):
+    await specwise.validate_json_schema(schema='{"type": "object"}')
+    assert api.last.url.path == "/v1/jsonschema/validate" and api.last_json() == {"schema": '{"type": "object"}'}
+    data = tmp_path / "data.json"
+    data.write_text('{"a": 1}')
+    await specwise.validate_json_schema(schema='{"type": "object"}', instance_path=str(data), draft="7")
+    assert api.last_json() == {"schema": '{"type": "object"}', "instance": '{"a": 1}', "instance_format": "yaml",
+                               "draft": "7"}
+    with pytest.raises(ToolError, match="exactly one of schema or schema_path"):
+        await specwise.validate_json_schema()
+
+
+async def test_json_arguments_through_the_server(api):
+    await specwise.server.call_tool("validate_json_schema", {"schema": '{"type": "object"}', "instance": "{}"})
+    assert api.last_json() == {"schema": {"type": "object"}, "instance": {}, "instance_format": "value"}
+    await specwise.server.call_tool("validate_json_schema", {"schema": "type: object", "instance": "a: 1"})
+    assert api.last_json() == {"schema": "type: object", "instance": "a: 1", "instance_format": "yaml"}
+    await specwise.server.call_tool("validate_openapi", {"spec": '{"openapi": "3.0.3"}'})
+    assert api.last_json() == {"spec": {"openapi": "3.0.3"}}
+    await specwise.server.call_tool("diff_openapi", {"base": '{"openapi": "3.0.3"}', "revision": SPEC_V2})
+    assert api.last_json() == {"base": {"openapi": "3.0.3"}, "revision": SPEC_V2}
+    await specwise.validate_json_schema(schema=True, instance=0)
+    assert api.last_json() == {"schema": True, "instance": 0, "instance_format": "value"}
+
+
+async def test_text_file_limits(tmp_path):
+    with pytest.raises(ToolError, match="No such file"):
+        files.read_text(str(tmp_path / "missing"), 100)
+    big = tmp_path / "big"
+    big.write_text("x" * 50)
+    with pytest.raises(ToolError, match="limit is"):
+        files.read_text(str(big), 10)
+    binary = tmp_path / "bin"
+    binary.write_bytes(b"\xff\xfe\x00")
+    with pytest.raises(ToolError, match="not UTF-8"):
+        files.read_text(str(binary), 100)