@acruxcoreai/mcp-server 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to `@acruxcoreai/mcp-server` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.2.0 — 2026-10-22
+
+### Added
+
+- **`optimize_prompt`**, **`get_optimize_report`** and **`promote_optimize_candidate`**
+  (`evaluations` toolset). Start an optimizer run, read each rewrite's score against the
+  baseline with the candidate id and rationale, and ship one as a new version.
+- `promote_optimize_candidate` refuses a rewrite that did not improve on at least one model,
+  or that regressed or has no scores on any, unless `promote_without_improvement` is set.
+  Read-only mode hides `optimize_prompt` and `promote_optimize_candidate`.
+- `promote_optimize_candidate` moves the alias the run was scored against by default. It
+  refuses when that alias now points at another version than the one scored, since nothing
+  compared the rewrite with it; `promote_without_improvement` overrides this too.
+- When six long rewrites do not fit in one result, `get_optimize_report` leaves out their
+  messages (`messagesOmitted`) and keeps every id and score; `candidate_id` reads one in full.
+- **`get_spending_limits`** (`gateway` toolset, read-only). Lists every budget with its
+  period, limit, live spend, `remainingUsd`, `exhausted` and reset time, names the virtual
+  key a budget belongs to, and lists the keys masked to their last four characters.
+
+### Changed
+
+- `run_prompt` and `chat_completion` now name the trace id on their summary line, as
+  `trace_id <uuid>`. The JSON part also carries `request-id`, another UUID, and a client
+  that took the first UUID it saw passed that one to `get_trace` and got a 404.
+
+### Fixed
+
+- `get_experiment_run` always reported "0 result(s)" on its summary line. It read
+  `results.length`, but the API returns `results` as `{ total, succeeded, errored }`.
+
+## 0.1.0 — 2026-10-18
+
+
+First release.
+
+### Added
+
+- **Model Context Protocol server for AcruxCore**, shipped two ways: a stdio binary
+  (`npx @acruxcoreai/mcp-server`) and a hosted Streamable HTTP endpoint at
+  `POST /api/v1/mcp` on any AcruxCore instance. Both register the same tools, so a tool
+  added once appears on both.
+- **28 tools across five toolsets.** `prompts` — `list_prompts`, `get_prompt`,
+  `render_prompt`, `diff_prompt_versions`, `create_prompt`, `commit_prompt_version`,
+  `promote_prompt_alias`. `gateway` — `run_prompt`, `chat_completion`, `list_models`,
+  `get_gateway_usage`. `tools` — `list_catalog_tools`, `get_catalog_tool`,
+  `sync_catalog_tool`, `execute_catalog_tool`. `traces` — `search_traces`, `get_trace`,
+  `get_trace_analytics`, `list_sessions`, `get_session`, `submit_trace_feedback`.
+  `evaluations` — `list_datasets`, `get_dataset`, `create_dataset`,
+  `add_dataset_example`, `run_experiment`, `list_experiment_runs`, `get_experiment_run`.
+- **Registry prompts as MCP prompts.** Every prompt in the team's registry is exposed
+  through MCP's prompts primitive at the `production` alias, with the version's template
+  variables as typed arguments. `ACRUXCORE_MCP_PROMPT_ALIAS` selects a different alias.
+- **`acruxcore://` resources.** `acruxcore://prompts/{name}/{alias}` reads back the raw,
+  unrendered template of the version an alias points at;
+  `acruxcore://traces/{traceId}` reads one trace with its full span tree.
+- **Names work wherever ids do.** Any tool taking a prompt or a catalog tool accepts the
+  name or the UUID, and an unknown name comes back as a `NOT_FOUND` listing the closest
+  matches rather than a silent near-miss.
+- **`--read-only` removes mutating tools from the listing** rather than refusing them
+  when called, so a model cannot choose a tool it never sees.
+- **`--toolsets`** narrows the surface to any subset of the five.
+- Configuration by environment variable or CLI flag, the flag winning:
+  `ACRUXCORE_API_KEY`, `ACRUXCORE_BASE_URL`, `ACRUXCORE_MCP_TOOLSETS`,
+  `ACRUXCORE_MCP_READ_ONLY`, `ACRUXCORE_MCP_PROMPT_ALIAS`,
+  `ACRUXCORE_MCP_MAX_TEXT_BYTES`, `ACRUXCORE_MCP_TIMEOUT_MS`.
+- **`initialize` instructions follow the registered tools.** A `--read-only` server
+  tells the model the connection is read-only and never names a tool it lacks.
+- **`diff_prompt_versions` says when two versions have identical messages**, and points
+  to `get_prompt` for comparing the bound models and settings.

package/LICENSE

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

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @acruxcoreai/mcp-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The [Model Context Protocol](https://modelcontextprotocol.io) server for
+[AcruxCore](https://acruxcore.com). It turns the platform — the prompt registry, the
+versioned tool catalog, the AI gateway, tracing and evaluation — into tools any MCP
+client can call, so an assistant can operate AcruxCore instead of being told which HTTP
+endpoints to hit.
+
+It also exposes your team's **registry prompts as MCP prompts**, so the prompts your
+production traffic renders show up in the client as ready-to-use templates, with the
+template variables as typed arguments.
+
+## Two ways to connect
+
+**Hosted — nothing to install.** Point an MCP client that supports remote servers at
+your AcruxCore instance:
+
+```
+https://api.acruxcore.com/api/v1/mcp
+```
+
+with an `Authorization: Bearer acx_sk_…` header. Create the key in the dashboard under
+**Settings → API keys**.
+
+**Local — stdio.** For clients that only speak stdio, or when you want to narrow the
+tool surface:
+
+```jsonc
+{
+  "mcpServers": {
+    "acruxcore": {
+      "command": "npx",
+      "args": ["-y", "@acruxcoreai/mcp-server"],
+      "env": {
+        "ACRUXCORE_API_KEY": "acx_sk_…",
+        "ACRUXCORE_BASE_URL": "https://api.acruxcore.com/api/v1"
+      }
+    }
+  }
+}
+```
+
+In Claude Code, one command does the same thing:
+
+```bash
+claude mcp add acruxcore -e ACRUXCORE_API_KEY=acx_sk_… -- npx -y @acruxcoreai/mcp-server
+```
+
+For a full walkthrough with a real Claude Code session, see
+[Connect Claude to AcruxCore with MCP](https://docs.acruxcore.com/docs/guides/connect-an-mcp-client).
+The endpoint reference is at
+[docs.acruxcore.com/api-reference/mcp](https://docs.acruxcore.com/api-reference/mcp).
+
+## Configuration
+
+Every option is an environment variable or a CLI flag; the flag wins.
+
+| Env | Flag | Default | Meaning |
+|---|---|---|---|
+| `ACRUXCORE_API_KEY` | `--api-key` | *required* | Your `acx_sk_…` key. |
+| `ACRUXCORE_BASE_URL` | `--base-url` | `https://api.acruxcore.com/api/v1` | Self-hosting? Point it at your instance. `/api/v1` is appended if you leave it off. |
+| `ACRUXCORE_MCP_TOOLSETS` | `--toolsets` | all | Comma-separated: `prompts`, `gateway`, `tools`, `traces`, `evaluations`. |
+| `ACRUXCORE_MCP_READ_ONLY` | `--read-only` | `false` | Drop every mutating tool from the listing. |
+| `ACRUXCORE_MCP_PROMPT_ALIAS` | `--prompt-alias` | `production` | Which alias the prompts primitive exposes. |
+| `ACRUXCORE_MCP_MAX_TEXT_BYTES` | `--max-text-bytes` | `40000` | Cap on the size of any single tool result. |
+| `ACRUXCORE_MCP_TIMEOUT_MS` | `--timeout-ms` | `60000` | Per-request HTTP timeout. |
+
+### Read-only mode
+
+`--read-only` removes the mutating tools from `tools/list` entirely rather than refusing
+them when called. A tool that is absent cannot be chosen by mistake and cannot be talked
+into running — which is the point of handing an agent a key it should not write with.
+
+## Tools
+
+**Prompts** — `list_prompts`, `get_prompt`, `render_prompt`, `diff_prompt_versions`,
+`create_prompt`, `commit_prompt_version`, `promote_prompt_alias`
+
+**Gateway** — `run_prompt`, `chat_completion`, `list_models`, `get_gateway_usage`, `get_spending_limits`
+
+**Tool catalog** — `list_catalog_tools`, `get_catalog_tool`, `sync_catalog_tool`,
+`execute_catalog_tool`
+
+**Traces** — `search_traces`, `get_trace`, `get_trace_analytics`, `list_sessions`,
+`get_session`, `submit_trace_feedback`
+
+**Evaluations** — `list_datasets`, `get_dataset`, `create_dataset`,
+`add_dataset_example`, `run_experiment`, `list_experiment_runs`, `get_experiment_run`,
+`optimize_prompt`, `get_optimize_report`, `promote_optimize_candidate`
+
+Anywhere a tool takes a prompt or a catalog tool, a **name works as well as a UUID**.
+
+## Prompts and resources
+
+Registry prompts appear through MCP's prompts primitive at the configured alias, with
+their template variables as arguments. MCP has no system role, so a template's system
+message is carried through as the leading `user` message with its text unchanged.
+
+Two resource templates are registered:
+
+- `acruxcore://prompts/{name}/{alias}` — the raw, unrendered template of the version an
+  alias points at.
+- `acruxcore://traces/{traceId}` — one trace with its full span tree.
+
+## The model behind the tools
+
+Three ideas explain nearly every tool here:
+
+- A **prompt** is a named container. It holds no messages itself.
+- A **version** is an immutable commit of that prompt's messages, numbered sequentially.
+- An **alias** — `production`, `staging`, anything else — is a moving pointer at one
+  version.
+
+Committing a version never moves an alias. `promote_prompt_alias` is what ships a
+change, and promoting an earlier version number is how you roll back.
+
+## License
+
+MIT

package/dist/bin.d.mts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node