<p align="center">
  <img src=".github/assets/lcv-ideas-software-logo.svg" alt="LCV Ideas &amp; Software" width="520" />
</p>

# ultrabrain-mcp

<p align="center">
  <strong>The local MCP reasoning gate from LCV Ideas &amp; Software for structured engineering thought.</strong>
</p>

<p align="center">
  <a href="https://github.com/LCV-Ideas-Software/ultrabrain-mcp/releases"><img alt="release" src="https://img.shields.io/github/v/release/LCV-Ideas-Software/ultrabrain-mcp?sort=semver" /></a>
  <a href="https://www.npmjs.com/package/@lcv-ideas-software/ultrabrain-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@lcv-ideas-software/ultrabrain-mcp.svg" /></a>
  <a href="https://github.com/LCV-Ideas-Software/ultrabrain-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/LCV-Ideas-Software/ultrabrain-mcp/actions/workflows/ci.yml/badge.svg" /></a>
  <a href="https://github.com/LCV-Ideas-Software/ultrabrain-mcp/actions/workflows/publish.yml"><img alt="Publish" src="https://github.com/LCV-Ideas-Software/ultrabrain-mcp/actions/workflows/publish.yml/badge.svg" /></a>
  <a href="https://ultrabrain-mcp.lcv.dev"><img alt="site" src="https://img.shields.io/badge/site-ultrabrain--mcp.lcv.dev-0f766e.svg" /></a>
  <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-green.svg" /></a>
</p>

**Install.** `npm install -g @lcv-ideas-software/ultrabrain-mcp` from npmjs.com, or `npm install -g @lcv-ideas-software/ultrabrain-mcp --registry=https://npm.pkg.github.com` from the GitHub Packages mirror.

**Version.** This source describes **1.2.17 / v01.02.17**. Consult the [npm package](https://www.npmjs.com/package/@lcv-ideas-software/ultrabrain-mcp) and [GitHub Releases](https://github.com/LCV-Ideas-Software/ultrabrain-mcp/releases) for current publication status. The historical `v01.02.16` tag records a failed publication attempt and is preserved; a tag alone is not proof of a published package. See [CHANGELOG.md](./CHANGELOG.md) for the changes and recovery context.

First publication started at **v01.00.00**. Public GitHub tags use the LCV Ideas & Software display convention `v00.00.00`; npm keeps normal SemVer.

## Change History

The version history at a glance:

| Release     | Package  | Date       | Notes                                                                                                                                                                                                                                      |
| ----------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `v01.02.17` | `1.2.17` | 08/09/2026 | Native governance and four-job publication, retaining the MCP bundle, license notices and clean-consumer checks. See the registry and Releases links above for publication status. |
| `v01.02.16` | `1.2.16` | 08/09/2026 | Failed publication attempt; its existing tag is preserved. Contains the qs update and earlier dependency-inventory and Linear Release changes, carried forward into the 1.2.17 source. |
| `v01.02.15` | `1.2.15` | 18/08/2026 | Quarantines persisted sessions whose branch collections are malformed (values of `branches`/`merged_branches` validated at load) instead of crashing MCP server startup with a `TypeError` in `relinkBranches`.                            |
| `v01.02.14` | `1.2.14` | 15/08/2026 | Delegates Trusted Publishing to the official npm client, removes the incompatible manual OIDC exchange probes, and waits for verified npmjs publication before writing to GitHub Packages.                                                 |
| `v01.02.13` | `1.2.13` | 15/08/2026 | Tag-only fail-closed canary: adding npm's operation header to the manual exchange still returned `401`; no npmjs, GitHub Packages, or GitHub Release artifact was published.                                                               |
| `v01.02.12` | `1.2.12` | 15/08/2026 | Tag-only fail-closed canary: the original manual Trusted Publisher preflight stopped before project code or artifact publication; superseded by the official-client recovery in `v01.02.14`.                                              |
| `v01.02.11` | `1.2.11` | 05/08/2026 | Adds the read-only `ultrabrain_server_info` tool (cross-review `server_info` parity): identity, release, capabilities, tool/prompt/resource surface, persistence `data_dir`/config, session count, engine limits, and security policy.     |
| `v01.02.10` | `1.2.10` | 05/08/2026 | Moves GitHub administration authority to a non-deploying protected environment, verifies canonical npm registry routing, and separates urgent CodeQL security updates from routine dependency batches.                                     |
| `v01.02.09` | `1.2.9`  | 03/08/2026 | Uses checksum-verified npm 12.0.2, accepts only documented `401`/identity-concealing `404` in the negative OIDC probe, requires exact `201` in the positive probe, isolates the writer, and updates vulnerable dependencies.               |
| `v01.02.08` | `1.2.8`  | 28/07/2026 | Completes the provenance-bound 1.2.5/1.2.6 release recovery, preserves the ambiguous 1.2.4 drafts as audit evidence, bundles MCP SDK 1.30.0, removes Socket/StepSecurity integrations, and makes the SDK license regression version-aware. |
| `v01.02.07` | `1.2.7`  | 22/07/2026 | Makes draft-release discovery eventual-consistency-safe by waiting for the exact server-issued release id before any asset upload.                                                                                                         |
| `v01.02.06` | `1.2.6`  | 22/07/2026 | Makes immutable release reconciliation preserve valid `false` boolean metadata at every release boundary.                                                                                                                                  |
| `v01.02.05` | `1.2.5`  | 22/07/2026 | Binds draft discovery, mutations, asset transfers, and final verification to the exact immutable release identity.                                                                                                                         |
| `v01.02.04` | `1.2.4`  | 22/07/2026 | Corrects npm tarball publication and adds provenance-safe tag/release recovery while preserving the immutable audit trail.                                                                                                                 |
| `v01.02.03` | `1.2.3`  | 22/07/2026 | Ships a self-contained MCP bundle, clean-consumer verification, and provenance-bound multi-registry publication.                                                                                                                           |
| `v01.02.02` | `1.2.2`  | 21/07/2026 | Security patch: updates transitive `body-parser` to 2.3.0, restoring request-size enforcement for invalid limit values (GHSA-v422-hmwv-36x6 / CVE-2026-12590).                                                                             |
| `v01.02.01` | `1.2.1`  | 17/07/2026 | Retro cross-review follow-up: `export` json+limit filters branches to the retained thoughts (latent leak, not tool-reachable), with a regression test.                                                                                     |
| `v01.02.00` | `1.2.0`  | 17/07/2026 | Audit remediation: correctness cluster (persistence, state machine, validation, protocol), a `vitest` unit-test layer, and Tier-1 features (mermaid review, template coverage, related thoughts, structuredContent).                       |
| `v01.01.01` | `1.1.1`  | 15/05/2026 | 4-gate quality directive compliance: added Biome, aligned CI, applied cosmetic source cleanup, and synchronized SERVER_VERSION to `1.1.1`.                                                                                                 |
| `v01.01.00` | `1.1.0`  | 12/05/2026 | Refinements for depth enforcement, active thought-reference validation, update record returns, real markdown merge output, optional file persistence, and expanded smoke coverage.                                                         |
| `v01.00.00` | `1.0.0`  | 12/05/2026 | First LCV Ultrabrain MCP release: branded tool surface, session lifecycle, branching, merging, validation, analysis, prompts, resources, Pages, CI, and publish automation.                                                                |

## What It Does

`ultrabrain-mcp` is an MCP server created by LCV Ideas & Software for local, structured reasoning before engineering work is closed. It gives agents a single branded gate for:

- step-by-step reasoning with branches and revisions;
- quality metrics, confidence, budget mode, and meta checkpoints;
- bias detection and counterexample prompts;
- explicit evidence, assumptions, alternatives, risks, and next actions;
- session review, validation, metrics, export, prompts, and resources.

The server does not call external LLM APIs. It is a local MCP reasoning scratchpad and quality gate, so source code and private task context stay inside the active MCP host.

## Tools

| Tool                   | Purpose                                                                      |
| ---------------------- | ---------------------------------------------------------------------------- |
| `ultrabrain_start`     | Create a reasoning session and optionally seed the first thought.            |
| `ultrabrain_think`     | Append the canonical Ultrabrain reasoning step.                              |
| `ultrabrain_update`    | Strengthen an existing thought with evidence, risks, confidence, or metrics. |
| `ultrabrain_branch`    | Create or continue an alternative reasoning path.                            |
| `ultrabrain_merge`     | Merge branch insights into a synthesis, best-evidence path, or decision.     |
| `ultrabrain_validate`  | Check evidence, alternatives, verification, bias, and closure gaps.          |
| `ultrabrain_analyze`   | Summarize quality, confidence, labels, bias counts, and recommendations.     |
| `ultrabrain_review`    | Render a session as summary, linear chain, tree, markdown, JSON, or Mermaid. |
| `ultrabrain_status`    | Show session state, thought count, branches, and latest quality score.       |
| `ultrabrain_history`   | Return recent thought records.                                               |
| `ultrabrain_export`    | Export a session as markdown, text, or JSON.                                 |
| `ultrabrain_metrics`   | Return aggregate session and reasoning metrics.                              |
| `ultrabrain_templates` | List built-in LCV engineering reasoning templates.                           |
| `ultrabrain_reset`     | Clear one session, or all sessions, removing their persisted files too.      |
| `ultrabrain_server_info` | Report server version, capabilities, tool surface, data dir, and limits.   |

## Canonical Example

```json
{
  "thought": "Map the failure, list evidence, compare alternatives, and choose the next verification step.",
  "thought_number": 1,
  "total_thoughts": 4,
  "next_thought_needed": true,
  "mode": "hybrid",
  "step_type": "analysis",
  "evidence": ["The failing behavior was reproduced locally."],
  "alternatives": ["patch the caller", "patch the shared parser"],
  "risks": ["a shared parser change can affect unrelated hosts"],
  "next_actions": ["run the focused test", "inspect the shared call path"],
  "quality_metrics": {
    "logical_consistency": 4,
    "completeness": 4,
    "objectivity": 4,
    "practicality": 5,
    "clarity": 5
  },
  "response_format": "json"
}
```

## MCP Configuration

Global npm installation target in the Windows environment used by LCV Ideas & Software:

```text
C:\npm-global\node_modules\@lcv-ideas-software\ultrabrain-mcp
```

Use the MCP server name `ultrabrain` in host configs:

```json
{
  "mcpServers": {
    "ultrabrain": {
      "command": "ultrabrain-mcp",
      "args": []
    }
  }
}
```

Development checkout and global installation are intentionally separate. Do not create a junction or symlink from `C:\npm-global\node_modules\@lcv-ideas-software\ultrabrain-mcp` to the workspace checkout.

Optional local persistence can be enabled per host with `ULTRABRAIN_STATE_DIR` or `ULTRABRAIN_PERSIST_DIR`. When unset, sessions remain process-local.

## Development

```sh
npm ci --ignore-scripts --no-audit --no-fund
npm run biome
npm run format:public:check
npm test
npm pack --dry-run
```

The smoke test starts the built MCP server over stdio, lists tools, verifies the branded `ultrabrain_*` surface, exercises session start, thought, branch, merge, validation, status, export, prompts, and resources.

## Release Automation

This source follows the native package-publication baseline:

- CI checks pull requests targeting `main` and pushes to `main`, retaining product tests, Biome, public-site formatting, bundle/license verification and clean-consumer coverage.
- Dependabot checks npm and GitHub Actions every day at 05h (UTC−03:00), including weekends. Minor/patch version updates are grouped; version-update majors remain separate. Security updates have their own group per ecosystem. GitHub native auto-merge is enabled for eligible same-repository Dependabot PRs, including majors, and waits for required checks.
- CodeQL uses GitHub Default Setup. Dependency Review, Zizmor and Scorecard remain repository-local official workflows.
- Pages builds `site/` on pull requests and deploys only from `main` to `ultrabrain-mcp.lcv.dev`.
- `Publish` runs on a push to `main` touching `package.json` and publishes only when its version changed. A dependency-only manifest edit without a package-version bump is a no-op.
- Four jobs run in order: a read-only build packs one tarball; npm publishes it through Trusted Publishing in `npm-production`; GitHub Packages publishes the same tarball using `GITHUB_TOKEN`; GitHub CLI creates the padded tag and GitHub Release last.
- Registry publication jobs consume the uploaded tarball without checking out or building product code. There is no separate auto-tag workflow, administrative PAT gate or repository-owned npm bootstrap.
- The official Linear Release integration remains separate from package publication. Direct third-party Actions stay pinned to reviewed immutable commit SHAs.

An existing tag is not publication evidence: the release decision refuses to reuse it. For an interrupted run, inspect the registry and Release state before using GitHub's [re-run failed jobs](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs) command, `gh run rerun RUN_ID --failed`. Recovery is best effort, not an exactly-once guarantee; a failed job may already have completed an external write. The [historical recovery runbook](./docs/HISTORICAL_RELEASE_RECOVERY.md) is archived evidence, not the current publication procedure.

## Research

See [docs/research-matrix.md](./docs/research-matrix.md). Ultrabrain imports ideas only at the architecture level. It does not copy third-party code, text, branding, non-English localization strings, or external model/API behavior.

## Repository conventions

- **License**: [Apache-2.0](./LICENSE). See [NOTICE](./NOTICE) and [THIRDPARTY](./THIRDPARTY.md).
- **Security disclosure**: see [SECURITY.md](./SECURITY.md).
- **Code of conduct**: see [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
- **Changelog**: [CHANGELOG.md](./CHANGELOG.md).
- **Contributing**: see [CONTRIBUTING.md](./CONTRIBUTING.md).
- **Sponsorship**: see the repo's `Sponsor` button or [central sponsor page](https://www.lcv.dev/sponsor).
- **Action pinning**: all GitHub Actions are pinned by full SHA per supply-chain hardening baseline.
- **Code owners**: [.github/CODEOWNERS](.github/CODEOWNERS).

## Links

- Site: [https://ultrabrain-mcp.lcv.dev](https://ultrabrain-mcp.lcv.dev)
- npmjs.com: [https://www.npmjs.com/package/@lcv-ideas-software/ultrabrain-mcp](https://www.npmjs.com/package/@lcv-ideas-software/ultrabrain-mcp)
- GitHub: [https://github.com/LCV-Ideas-Software/ultrabrain-mcp](https://github.com/LCV-Ideas-Software/ultrabrain-mcp)
- Sponsors: [https://github.com/sponsors/LCV-Ideas-Software](https://github.com/sponsors/LCV-Ideas-Software)

## License

Apache-2.0. See [LICENSE](./LICENSE), [NOTICE](./NOTICE), and [THIRDPARTY](./THIRDPARTY.md).

---

<p align="center"><span style="font-size: 1.5em;"><strong>Copyright © 2026 LCV Ideas &amp; Software</strong></span><br><sub>LEONARDO CARDOZO VARGAS TECNOLOGIA DA INFORMACAO LTDA<br>Rua Pais Leme, 215 Conj 1713 - Pinheiros<br>São Paulo - SP - CEP 05424-150<br>CNPJ: 66.584.678/0001-77 - IM: 3039854</sub></p>