mcp-openapix 0.1.0__tar.gz

mcp_openapix-0.1.0/.gitattributes

@@ -0,0 +1,4 @@
+* text=auto eol=lf
+*.{cmd,[cC][mM][dD]} text eol=crlf
+*.{bat,[bB][aA][tT]} text eol=crlf
+

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

@@ -0,0 +1,84 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+    tags: ["*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint and format
+        run: |
+          uv run ruff check src/ tests/
+          uv run ruff format --check src/ tests/
+
+      - name: Type check
+        run: uv run pyright
+
+      - name: Test
+        run: uv run pytest tests/ -v --tb=short
+
+  publish:
+    name: Release
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/mcp-openapix/${{ github.ref_name }}/
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@ae62891fec2bb8e7d6c99fc78c9fec3a63790f8d # v10.0.0
+        with:
+          enable-cache: true
+
+      - name: Build Python package distributions
+        run: uv build
+
+      - name: Publish Python package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Install MCP Registry publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+
+      - name: Update MCP Registry manifest version
+        run: |
+          jq --arg version "${GITHUB_REF_NAME}" '.version = $version | .packages[].version = $version' server.json > server.tmp
+          mv server.tmp server.json
+
+      - name: Authenticate MCP Registry publisher
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish server metadata to MCP Registry
+        run: ./mcp-publisher publish

mcp_openapix-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Project / local
+.env
+.env.local
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environment (uv)
+.venv/
+env/
+venv/
+
+# Build / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Test / coverage (pytest, pytest-cov)
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+cover/
+
+# Ruff
+.ruff_cache/
+
+# mypy
+.mypy_cache/
+
+# PyPI (credentials)
+.pypirc
+
+# AI agent
+*-progress.md
+.claude/settings.local.json

mcp_openapix-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+# See https://pre-commit.com for more
+# Run: pre-commit install
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: uv run pyright
+        language: system
+        types: [python]
+        pass_filenames: false

mcp_openapix-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

mcp_openapix-0.1.0/AGENTS.md

@@ -0,0 +1,138 @@
+# Agent Instructions
+
+Rules AI agents must follow when working in this repository.
+
+---
+
+## Commit messages
+
+Use **Conventional Commits**.
+
+### Header
+
+* Format: `<type>(optional scope): summary`
+* Use lowercase types (`feat`, `fix`, `ci`, `chore`, `docs`)
+* Use scopes when relevant
+* Write summaries in lowercase, imperative mood
+
+### Body
+
+* Leave a blank line after the header
+* Explain **why**, not what
+* Use imperative, present tense
+* Wrap lines at ~72 characters
+
+The body is optional for trivial changes.
+
+---
+
+## Commits
+
+When generating commits via a shell:
+
+* Do **not** pass generated messages directly to `git commit -m`
+* Write the commit message to a file or standard input
+* Use `git commit -F <file>` or `git commit -F -`
+* Disable shell expansion when writing commit messages
+
+This avoids issues with backticks, quotes, and other shell-expanded characters in
+generated commit messages.
+
+---
+
+## Attribution
+
+Every AI-assisted commit, tag, PR, comment, reply, or message an agent writes for
+someone must carry an `Assisted-by` trailer:
+
+```
+Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]
+```
+
+| Field             | Description                                               |
+|-------------------|-----------------------------------------------------------|
+| `AGENT_NAME`      | AI tool or framework (e.g. `Claude`, `Cursor`, `Copilot`) |
+| `MODEL_VERSION`   | Specific model (e.g. `claude-opus-4-6`)                   |
+| `[TOOL1] [TOOL2]` | Optional specialized analysis tools; omit everyday tools  |
+
+* Place it at the **end**, after a blank line: a git trailer in commits, the last line
+  of the body everywhere else.
+* Skip it only for text the user dictates verbatim.
+* Use only `Assisted-by` — no `Co-Authored-By`, no `Made with …`, no hand-written `Sent
+  using …`, no other footers.
+
+Example:
+
+```
+Assisted-by: Claude:claude-opus-4-6 coccinelle sparse
+```
+
+---
+
+## Code style
+
+Follow existing project conventions.
+
+* Match formatting, naming, and file structure already in use
+* Wrap prose and Markdown matching `line-length` in `pyproject.toml`; leave code blocks,
+  tables, and URLs unwrapped
+* Do not reformat unrelated code
+* Prefer small, focused changes
+* Avoid introducing new patterns without clear benefit
+
+### Language-specific rules
+
+* Respect `.editorconfig` when present
+* Do not disable lint rules without justification
+* Prefer explicit, readable code over clever abstractions
+* Ensure all changes pass `ruff check .`, `ruff format --check .`, `pyright`, and
+  `pytest`
+
+---
+
+## `uv` Workflow Rules
+
+* Use `uv` exclusively for dependency management instead of `pip`
+* Always prefix tool and script invocations with `uv run` so they execute inside the
+  managed environment
+* Do not manually create, activate, or delete `.venv` directories
+
+---
+
+## Vendor neutrality
+
+This server fronts **any** OpenAPI service. Nothing in `src/`, `tests/`,
+`config.example.json` or the docs may name a specific vendor, brand, product, internal
+hostname, or employer.
+
+* Example configs use `example.com` and placeholder names (`acme`, `items`)
+* A behavior that exists because one upstream happens to work a certain way is
+  documented by the **property** it relies on, never by who it was observed in
+* Vendor-specific login belongs in a token helper, in its own repository — see
+  `docs/token-protocol.md`
+* The `[OpenAPI]` tool-description prefix required below names the protocol this server
+  speaks, not a vendor, and is not an exception to this rule
+
+---
+
+## MCP Metadata
+
+Normative, high-density metadata: enough for correct tool and parameter selection,
+minimal to reduce token cost.
+
+* **The tool/parameter description MUST start with [OpenAPI], followed by a Verb-Object
+  fragment**, e.g. `[OpenAPI] Execute an API operation`, `[OpenAPI] List OpenAPI
+  operations`, `[OpenAPI] Get the full OpenAPI schema`.
+* **Use tag-based lineage (Src: <Entity>) for parameters that refer to entities the
+  server can enumerate** (e.g. platform → Src: platforms, region → Src: regions, service
+  → Src: services, operation id → Src: operations).
+* **Every tool MUST declare `ToolAnnotations`** — hints, not guarantees, that a host
+  turns into a consent prompt.
+* `read_only_hint=True` claims the tool changes nothing anywhere: writing a local file
+  is a change.
+* `destructive_hint` and `idempotent_hint` matter only when `read_only_hint=False` — set
+  both there, omit both otherwise. Both are positive claims: `destructive_hint=False`
+  promises additive-only writes, `idempotent_hint=True` promises a repeat call with the
+  same arguments has no further effect.
+* `open_world_hint` tracks the domain of interaction, not the I/O — `False` only when
+  that domain is fixed at build time (bundled data, local config).

mcp_openapix-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

mcp_openapix-0.1.0/LICENSE

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

@@ -0,0 +1,284 @@
+Metadata-Version: 2.5
+Name: mcp-openapix
+Version: 0.1.0
+Summary: A Model Context Protocol (MCP) server that fronts any OpenAPI service: discover operations from its spec and call them, with bearer tokens supplied by pluggable helper commands.
+Project-URL: Homepage, https://github.com/alyiox/mcp-openapix
+Project-URL: Repository, https://github.com/alyiox/mcp-openapix.git
+Project-URL: Issues, https://github.com/alyiox/mcp-openapix/issues
+Author-email: Joh X <alyiox@hotmail.com>
+Maintainer-email: Joh X <alyiox@hotmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,api,llm,mcp,model-context-protocol,openapi,rest,swagger
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.13
+Requires-Dist: filelock>=3.30
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp[cli]>=2.0.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: anyio>=4.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.15; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcp-openapix
+
+[![CI](https://github.com/alyiox/mcp-openapix/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/alyiox/mcp-openapix/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mcp-openapix.svg)](https://pypi.org/project/mcp-openapix/)
+[![Python
+3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+<!-- mcp-name: io.github.alyiox/mcp-openapix -->
+
+[MCP](https://modelcontextprotocol.io) server that fronts **any** OpenAPI service behind
+four generic tools.
+
+An agent finds operations in each deployment's OpenAPI document and calls them; the
+server resolves the URL, obtains a bearer token, and builds the request. Discovery is
+`list_platforms`, `list_endpoints` and `describe_endpoint`; execution is the generic
+proxy `call_endpoint`.
+
+```
+example / us / items / prod
+  │     │     │      └── env ......... which deployment URL a call reaches
+  │     │     └───────── service ..... one backend, one OpenAPI spec
+  │     └─────────────── region ...... a geographic deployment
+  └───────────────────── platform .... the product or API family
+```
+
+## Requirements
+
+- Python 3.13+ and [`uv`](https://docs.astral.sh/uv/)
+- A `config.json` describing the deployments you hold credentials for
+
+## Quick start
+
+Set up your config (see [Configuration](#configuration)), then run the server:
+
+```bash
+# Run directly with uvx (no clone needed)
+npx -y @modelcontextprotocol/inspector@latest uvx mcp-openapix
+```
+
+```bash
+# Or run from source
+npx -y @modelcontextprotocol/inspector@latest uv run mcp-openapix
+```
+
+## Configuration
+
+`config.json` MUST live at `~/.config/mcp-openapix/config.json`
+(`%USERPROFILE%\.config\…` on Windows). `config.example.json` is a full template.
+
+```json
+{
+  "headers": { "accept": "application/json" },
+  "defaults": { "platform": "example", "region": "us", "service": "items", "env": "prod" },
+  "platforms": {
+    "example": {
+      "regions": {
+        "us": {
+          "services": {
+            "token_helper": "us",
+            "items": {
+              "desc": "Catalogue and inventory API",
+              "spec_path": "/swagger/v1/swagger.json",
+              "canonical_env": "prod",
+              "envs": {
+                "prod": { "url": "https://api.example.com/items" },
+                "dev":  { "url": "https://api-dev.example.com/items" }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "token_helpers": {
+    "us": {
+      "command": "token-helper",
+      "args": ["issue"]
+    }
+  }
+}
+```
+
+### `platforms`
+
+A hierarchy of `platform → region → services → service → env`. Each service declares:
+
+| Field | Notes |
+|---|---|
+| `spec_path` | Required. The OpenAPI JSON endpoint relative to the service URL |
+| `canonical_env` | Required when more than one env is configured — the env whose URL the spec is fetched from |
+| `envs` | Required. One entry per deployment environment, each carrying a full base `url` |
+| `desc` | Optional. A short description surfaced by `list_platforms` |
+| `token_helper` | Optional. The token helper this level binds to |
+
+The `services` object may also contain a `token_helper` default applying to all services
+in that region. A service or environment can override it.
+
+### `token_helpers`
+
+Named token helpers, in the same shape as an MCP server entry:
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `command` | yes | — | Resolved on `PATH`; never run through a shell |
+| `args` | no | `[]` | Passed verbatim |
+| `timeout` | no | `60` | Seconds before the helper's process group is killed; at most `300` |
+
+The config names a command and nothing else, so `config.json` holds **no secrets**.
+The complete helper invocation and output contract is documented in
+[`docs/token-protocol.md`](docs/token-protocol.md).
+
+Which helper a call uses is resolved most-specific-first:
+
+```
+env.token_helper → service.token_helper → services.token_helper
+→ region.token_helper → platform.token_helper → defaults.token_helper
+```
+
+If no level declares a helper, the deployment is unauthenticated. Omit
+`token_helper` for public deployments.
+
+### `headers`
+
+Constant headers added to every API call — for APIs that require a tenant, product or
+locale header:
+
+```json
+"headers": { "accept": "application/json", "x-product": "example" }
+```
+
+### `defaults`
+
+Makes every tool argument optional: a call falls back to `defaults.platform`, `.region`,
+`.service`, `.env`, `.username` and `.token_helper` when they are omitted.
+
+### Top-level options
+
+| Field | Default | Notes |
+|---|---|---|
+| `truncate_threshold` | `1024` | Response bytes returned inline before truncating to a preview |
+| `response_cache_ttl` | `3600` | Seconds a truncated body stays readable at its resource URI |
+| `spec_refresh` | `{"auto": true, "interval": 7}` | Background spec refresh; `interval` is days and MAY be fractional |
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `list_platforms` | Every platform with its regions, services, and envs |
+| `list_endpoints` | A service's operations, filtered by `query`, `tag` or `method` |
+| `describe_endpoint` | One operation plus the transitive closure of the schemas it references |
+| `call_endpoint` | Execute an operation, or a raw `method` + `path` absent from the spec |
+
+### Operation ids
+
+Many OpenAPI documents omit `operationId`, so the server synthesizes one as `"<METHOD>
+<path>"`:
+
+```
+POST /api/items
+└─┬─┘ └───┬───┘
+method  path as the spec declares it
+```
+
+Where a spec does declare an `operationId`, that value wins.
+
+## Specs
+
+Specs are **not** bundled. Each deployment's document is fetched on demand — an
+unauthenticated `GET` — and cached under
+`~/.cache/mcp-openapix/{platform}/{region}/{service}.json`.
+
+A document MUST declare at least one operation before it is installed, so a deployment
+answering `200` with an error body cannot replace a working snapshot with one that
+serves nothing.
+
+Cached specs refresh in the background: once at startup, then every
+`spec_refresh.interval` days. Set `auto` to `false` to stop it; the manual lever still
+works:
+
+```bash
+uvx mcp-openapix --refresh
+```
+
+## MCP resources
+
+| Resource URI | Description |
+|---|---|
+| `openapi://responses/{request_id}` | Full body of a truncated `call_endpoint` response |
+| `openapi://curl/{request_id}` | Equivalent curl command for a `call_endpoint` request |
+
+Both expire `response_cache_ttl` seconds after the call. The curl command may embed
+a short-lived token.
+
+## Tokens at rest
+
+Tokens are cached in memory and, when expiry metadata is available, under
+`~/.cache/mcp-openapix/tokens/` (mode `0600`) keyed by the token-helper declaration
+and username. This lets client sessions share a login without spawning a helper each.
+A `401` retires the cached token so the next call obtains a fresh one. To clear them all:
+
+```bash
+uvx mcp-openapix --logout
+```
+
+## MCP host examples
+
+<details> <summary><b>Cursor / Claude Code</b></summary>
+
+```json
+{
+  "mcpServers": {
+    "openapi": { "command": "uvx", "args": ["mcp-openapix"] }
+  }
+}
+```
+
+</details>
+
+<details> <summary><b>Codex</b></summary>
+
+```toml
+[mcp_servers.openapi]
+command = "uvx"
+args = ["mcp-openapix"]
+```
+
+</details>
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv run pytest
+```
+
+All four MUST pass; see `AGENTS.md`. Tests use
+[`respx`](https://github.com/lundberg/respx) to mock HTTP and real subprocesses for
+token helpers, so no live API access is required.
+
+## License
+
+[MIT](LICENSE).