Metadata-Version: 2.4
Name: furox-scientific-toolkit-mcp
Version: 0.2.2
Summary: Provider-neutral local and remote MCP hub for seven Furox-Art public research tools
Author: Furox-Art
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Furox-Art/scientific-toolkit
Project-URL: Issues, https://github.com/Furox-Art/scientific-toolkit/issues
Project-URL: Documentation, https://github.com/Furox-Art/scientific-toolkit/blob/main/README.md
Project-URL: Source, https://github.com/Furox-Art/scientific-toolkit
Keywords: model-context-protocol,mcp,scientific-computing,ai-agents,research-tools,python
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
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 :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: oauth
Requires-Dist: PyJWT[crypto]<3,>=2.9; extra == "oauth"
Dynamic: license-file

# Furox Scientific Toolkit — MCP Gateway

**Provider-neutral Model Context Protocol gateway for seven existing Furox-Art public repositories.**
The upstream packages stay independent, with their original names and version histories.
This repository is an integration hub, not a merge of source trees.

Project website: [Furox Scientific Toolkit](https://www.furoxscientifictoolkit.lovie.me/).
Published Python package: [furox-scientific-toolkit-mcp on PyPI](https://pypi.org/project/furox-scientific-toolkit-mcp/).

**Status:** local stdio and authenticated stateless Streamable HTTP transports
are implemented. The public Render deployment at
[`https://scientific-toolkit.onrender.com/health`](https://scientific-toolkit.onrender.com/health)
has been verified on 2026-10-08: 7 installed CLI executables and **12/12
authenticated loopback MCP HTTP startup checks passed**, including six safe
scientific CLI adapter calls. This proves deployment plumbing, **not**
scientific correctness or external Claude/ChatGPT client login. OAuth
issuer/JWKS remains **not configured**.

## Seven upstream repositories

| Public repository | Role | MCP tool(s) |
| --- | --- | --- |
| [axiomize](https://github.com/Furox-Art/axiomize) | Scientific models and verification | `axiomize_intake`, `axiomize_model` |
| [scientific-computing-system](https://github.com/Furox-Art/scientific-computing-system) | Pure-Python numerical computation | `cds_stats` |
| [scientific-computing-system-2.0](https://github.com/Furox-Art/scientific-computing-system-2.0) | NumPy/SciPy computation | `cds2_stats` |
| [plan-auditor](https://github.com/Furox-Art/plan-auditor) | Independent execution verification | `plan_auditor_inspect`, `plan_auditor_audit` |
| [quantum-reasoning-skill](https://github.com/Furox-Art/quantum-reasoning-skill) | Reasoning protocol/skill inspector | `quantum_skill_validate` |
| [axiomize-quantum-skills-2.0](https://github.com/Furox-Art/axiomize-quantum-skills-2.0) | Bundled modeling + branch-scoring controller | `axiomize_reason_score` |
| [eq-layer](https://github.com/Furox-Art/eq-layer) | Response-control and intent routing | `eq_layer_route` |

`axiomize-quantum-skills-2.0` already packages Axiomize, so this hub does **not**
register its Axiomize MCP tools a second time. `quantum-reasoning-skill` is a skill
protocol, not a quantum computer or a validated performance improvement. EQ-Layer is
communication-control infrastructure, not a scientific data validator.

## Local installation

Requires **Python 3.10+**. Install the published MCP gateway from PyPI,
or install it in editable mode from a source checkout for development:

```sh
python -m pip install furox-scientific-toolkit-mcp
# For a source checkout instead: python -m pip install -e .
# Select upstream packages you actually need:
python -m pip install axiomize scientific-computing-system
python -m pip install scientific-computing-system-2.0
python -m pip install plan-auditor quantum-reasoning-skill eq-layer
# The bundled Axiomize/quantum package may replace the standalone
# Axiomize CLI. Install it in a separate environment (below).
python -m scientific_toolkit_mcp
```

To enable the bundled reasoning controller separately, create a dedicated virtual
environment and install `axiomize-quantum-skills-2.0` there. Then set
`SCITOOL_REASON_BIN` to that environment's `axiomize-reason` executable.
This avoids the shared `axiomize` CLI clashing with standalone Axiomize.

The final command starts an **MCP stdio process**. It waits for JSON-RPC requests on
stdin and writes JSON-RPC only to stdout; it is not a text chat or HTTP server.

**Any compatible local stdio MCP client:** add this server to your MCP
configuration (adjust `python` or use the absolute path to the correct venv Python):

```json
{
  "mcpServers": {
    "scientific-toolkit": {
      "command": "python",
      "args": ["-m", "scientific_toolkit_mcp"]
    }
  }
}
```

In a running MCP client, call `toolkit_catalog` to see all seven repos, and
`toolkit_doctor` to check which upstream CLIs are installed. Missing packages
produce explicit `NOT_INSTALLED` errors rather than fabricated data.

## Remote MCP: provider-neutral Streamable HTTP

The 7-repository catalog is available through compatible remote MCP clients using
`POST /mcp` (stateless JSON-RPC), when authenticated. `GET /health` is public.
A Render deployment currently serves `https://scientific-toolkit.onrender.com/mcp`;
use the private credential configured in Render and **never publish that token**.
To run your own instance instead:

```sh
# Generate a long random secret outside the repo and store it as a provider secret.
# Supply SCITOOL_MCP_BEARER_TOKEN through environment configuration.
python -m scientific_toolkit_mcp.http_server
```

Required variable: `SCITOOL_MCP_BEARER_TOKEN` (nonempty, kept outside Git).
Optional variables: `PORT` (default `8000`) and `SCITOOL_ALLOWED_ORIGINS`
(comma-separated exact origin URLs). **No web origin is allowed by default.**
Non-browser clients normally omit `Origin`; browser-origin requests require a
configured allowlist entry and receive restricted CORS headers. Do not put
bearer secrets in browser JavaScript or check them into a Git repository.
Use TLS/HTTPS at the hosting reverse proxy and restrict access to trusted users.

Remote clients must support **MCP Streamable HTTP and an explicit bearer-token
header**. Use the URL `https://YOUR-HOST/mcp` and set
`Authorization: Bearer YOUR_SECRET` in that client's supported configuration.
Some clients require OAuth discovery/registration instead and therefore **cannot
connect directly** to this bearer-only server without an OAuth-compatible proxy.
This is a client capability distinction, not a Claude/ChatGPT/Cursor restriction.

The `toolkit_catalog` covers all seven repositories. Authenticated HTTP clients
may call the **read-only** `plan_auditor_inspect` only after the administrator
configures `SCITOOL_WORKSPACE_DIR` to a trusted existing project directory.
`plan_auditor_audit` can execute arbitrary project verification code and therefore
remains **local-only** (10 remote tools out of 11 local tools). Setting
`SCITOOL_ALLOW_AUDIT_EXECUTION=1` does **not** override this HTTP safeguard. Missing upstream CLI packages return
`NOT_INSTALLED`, never a fabricated PASS. Install the desired upstream packages
in your deployment and use isolated environments for colliding Axiomize CLIs.
No hosting fees are necessary to use the local stdio gateway.

### Portability

- Local: Claude Desktop, Cursor, Codex, and other stdio-capable MCP clients
  (configure each with its own supported launcher settings). This is protocol-level
  portability, not proof that a particular client's end-to-end setup was tested.
- Remote: any Streamable-HTTP MCP client that accepts a custom bearer header.
- Model-agnostic: the MCP server performs no proprietary LLM calls or inference.
- Cross-application compatibility still requires live client-specific testing.

## Optional executable overrides

For independent virtual environments, set environment variables to **executable
paths only**, not commands with arguments:

| Environment variable | Default executable |
| --- | --- |
| `SCITOOL_AXIOMIZE_BIN` | `axiomize` |
| `SCITOOL_CDS_BIN` | `cds` |
| `SCITOOL_CDS2_BIN` | `cds2` |
| `SCITOOL_AUDITOR_BIN` | `plan-auditor` |
| `SCITOOL_QUANTUM_BIN` | `quantum-reasoning` |
| `SCITOOL_REASON_BIN` | `axiomize-reason` |
| `SCITOOL_EQ_BIN` | `eq-layer` |

### Upstream distribution pins

The bundled Axiomize variant installs its own top-level `axiomize` module, so
an isolated install directory that reaches `sys.path` (for example through
`PYTHONPATH`) can silently replace the standalone Axiomize distribution. The
gateway therefore treats `axiomize` as a **pinned distribution**: when more than
one `sys.path` entry provides the `axiomize` module, `axiomize` tool calls fail
with a loud `BAD_CONFIGURATION` error instead of running whichever distribution
happens to come first. `SCITOOL_PIN_AXIOMIZE` additionally pins the exact
expected version (for example `SCITOOL_PIN_AXIOMIZE=1.12.5`), and a resolved
version that differs fails the call. A missing executable still reports
`NOT_INSTALLED`.

### Verification safety

The Plan Auditor `audit` operation executes the plan's configured checks. It is
**disabled by default**. To opt in for a trusted local workspace, configure both:

- `SCITOOL_WORKSPACE_DIR`: an already-existing trusted project directory
- `SCITOOL_ALLOW_AUDIT_EXECUTION=1`: grants the audit tool permission to run those checks

`plan_auditor_inspect` also requires the configured workspace but does not
assert task completion. All executable commands use fixed allowlisted command
forms and `subprocess` **without a shell**. No user-selected paths or arbitrary
command strings are accepted via MCP. Restrict access to the client session:
the HTTP gateway requires authentication and never exposes the executable audit tool.
It exposes read-only plan inspection only for a configured trusted workspace.

## Scope, evidence, and limitations

- Axiomize `model` operations require the actual upstream Model IR request; the
  gateway does not invent missing model assumptions or validation outcomes.
- The two numerical packages have independent statistics adapters; their
  outputs and numerical algorithms are not silently conflated.
- Each subprocess response includes exit code and stdout. Nonzero exit codes
  are MCP errors, and `UNKNOWN` is never promoted to a successful verification.
- The bundled reasoning tool's thresholds remain uncalibrated reference defaults.
- Any compatible AI client can serve as an **orchestrator**, not the validator:
  scientific claims still require reproducible numerical and empirical evidence.
- This repo does not represent an incorporated legal company or promise Claude
  startup program eligibility. No deployment costs have been paid.

## Tests

```sh
python -m unittest discover -s tests -v
```

CI exercises JSON-RPC initialization, list/call, seven-repository catalog,
input validation, fail-closed audit defaults, upstream failures, and fake-CLI
transport. The fake executable tests validate the **integration plumbing**;
actual upstream numerical correctness remains the responsibility of each
repository's own tests and a future cross-package integration suite.

## Independent integration evidence

Three CI suites provide progressively stronger, but limited, verification:

1. [Protocol/unit tests](https://github.com/Furox-Art/scientific-toolkit/actions/workflows/tests.yml)
   check stdio and authenticated HTTP handling, argument validation, safe defaults,
   and fail-closed errors. Fake CLI tests are plumbing tests, not scientific evidence.
2. [Published upstream package smoke checks](https://github.com/Furox-Art/scientific-toolkit/actions/workflows/real-upstream.yml)
   install all seven distributions separately and invoke their real CLIs through
   the gateway. The Plan Auditor profile checks the installed CLI and refusal
   to audit an unconfigured plan, *not* successful verification of research.
   This workflow also checks the live Render `/health` route and ensures that
   unauthenticated MCP tool calls receive HTTP 401.
3. [Official SDK interoperability](https://github.com/Furox-Art/scientific-toolkit/actions/workflows/sdk-client.yml)
   starts a temporary authenticated HTTP server, connects with the official MCP
   Python client, negotiates a session, enumerates the ten remote-safe tools,
   and calls `toolkit_catalog`. A generated CI-only token is used.

**Deployment scope:** CI tests both isolated packages and all seven installed
in one environment. The live Render service also passed 12/12 authenticated
HTTP tests using its own private bearer credential over loopback; this
includes six tool-execution paths and the seven-CLI availability check.
No external ChatGPT/Claude OAuth sign-in was tested. The optional OAuth
resource verifier is implemented, but a trusted authorization server
must still be connected before OAuth-based clients can log in. Never
publish or transmit the production bearer secret in GitHub or screenshots.

## Deploy all seven upstream packages on Render

The currently published Render service originally installed only the MCP gateway
with `pip install -e .`. This repository now includes a separate installation
script that installs six upstream distributions into the system environment and
the bundled Axiomize variant into an isolated package directory. To apply this to the
**existing** service, set its **Build Command** in Render to:

```sh
bash scripts/render-build.sh
```

Keep its **Start Command** unchanged:

```sh
python -m scientific_toolkit_mcp.http_server
```

Do **not** replace or reveal the existing `SCITOOL_MCP_BEARER_TOKEN`.
Rebuild/redeploy the existing free service after changing the build command.
The [full-stack installation workflow](https://github.com/Furox-Art/scientific-toolkit/actions/workflows/full-stack-install.yml)
checks seven real CLI invocations in one CI environment. That does not prove all
dependencies fit the Render Free 512 MB runtime limit or that production has
installed them: inspect Render build logs and run authenticated calls separately.
If the host runs out of memory, use separate workers or a larger instance rather
than claiming all seven are running.

## Optional OAuth 2.1 resource-server support

The public HTTP gateway supports **opt-in verification** of RS256-signed OAuth
access tokens from an actual independently configured identity provider. It
exposes `/.well-known/oauth-protected-resource/mcp` and includes protected
resource metadata in unauthorized responses **only when configured**.

The OAuth verifier requires `pip install -e '.[oauth]'` (included in the Render
build script) and all of these private Render environment settings:

| Environment variable | Configuration |
| --- | --- |
| `SCITOOL_OAUTH_ISSUER` | Trusted provider's HTTPS issuer URI |
| `SCITOOL_OAUTH_JWKS_URI` | Provider's HTTPS public JWKS endpoint |
| `SCITOOL_OAUTH_RESOURCE_URI` | `https://scientific-toolkit.onrender.com/mcp` |
| `SCITOOL_OAUTH_REQUIRED_SCOPE` | `mcp:tools` (provider must issue it) |

The gateway checks signature, audience, issuer, subject, expiration and scope,
and still recognizes the administrator's original bearer token. The server
does **not** issue tokens, run an OAuth consent screen or register clients.
A production identity provider must separately support proper OAuth 2.1,
PKCE, client registration/metadata and audience-bound access tokens.
An OAuth login via Claude or ChatGPT is **not yet confirmed** and must not
be advertised as active without a real IdP and app-specific authentication test.

## Python package and PyPI publishing

The gateway's Python distribution is named [`furox-scientific-toolkit-mcp`](https://pypi.org/project/furox-scientific-toolkit-mcp/)
(version `0.2.0`), with import name `scientific_toolkit_mcp`. The package has
been published on PyPI and can be installed with:

```sh
python -m pip install furox-scientific-toolkit-mcp
```

Publishing the MCP gateway does not by itself verify integration with Claude
or any other hosted AI client. Claude may be used as an orchestration client
where MCP transport and authentication are properly configured; a production
Claude OAuth sign-in and end-to-end client integration have not been verified.

The token-free GitHub Actions release workflow includes tests, sdist/wheel
building, metadata validation, and an installed-wheel smoke test. See
[PyPI publishing setup](docs/pypi-publishing.md) for the exact publisher fields
and release procedure.

Installing the gateway does not install the seven upstream scientific tools:
use `toolkit_doctor` to distinguish available programs from missing ones.

## Repository and license

Project: https://github.com/Furox-Art/scientific-toolkit

The MCP gateway is licensed under **Apache License 2.0**, as recorded in the
repository root `LICENSE`. The seven upstream repositories retain their own
independent licenses, names and version histories. Public Render health and
anonymous access controls have been checked by CI; authorized production calls
against upstream scientific programs have not yet been confirmed.
