ultrabrain-mcp: Instructions file for Codex

AGENTS.md - ultrabrain-mcp

Pointer for AI agents working in this repository.

Project

• Repository: https://github.com/LCV-Ideas-Software/ultrabrain-mcp
• Package: @lcv-ideas-software/ultrabrain-mcp
• Site: https://ultrabrain-mcp.lcv.dev
• Branch: main
• License: Apache-2.0

Runtime Shape

This repository is a TypeScript MCP stdio server. Source lives in src/, build output lives in dist/, and the runtime entry point is dist/index.js.

The public MCP surface is LCV-branded. Tool names must use the ultrabrain_* prefix. Do not add legacy third-party tool names as public aliases.

Mandatory Gates

npm test
npm run biome
npm run format:public:check
npm pack --dry-run

For local MCP runtime checks after installation:

ultrabrain-mcp

Do not run the server directly in a blocking shell unless it is attached to an MCP client or a smoke harness; stdio MCP servers wait for protocol input.

Release and Publishing

• Do not publish from the workstation.
• publish.yml runs on pushes to main touching package.json; only a changed package version initiates publication. Dependency-only manifest edits do not.
• Its four jobs build and pack once without publishing permissions, publish the same tarball to npmjs.com through OIDC in npm-production, mirror it to GitHub Packages with GITHUB_TOKEN, then create the padded tag and GitHub Release last.
• The first public release was v01.00.00 from npm package version 1.0.0. Current tags retain the padded display convention (v00.00.00); npm uses SemVer.
• Do not restore auto-tagging, administrative PAT gates, release-policy engines or a custom npm bootstrap. Retain product build, bundled-license verification and clean-consumer tests; these are not retired governance controllers.
• An existing tag does not prove publication succeeded. Check partial registry writes before a native gh run rerun RUN_ID --failed; reruns are best effort, not an exactly-once transaction. Do not move or recreate historical tags.
• CodeQL uses Default Setup. Native Dependabot auto-merge, Dependency Review, Zizmor, Scorecard and Linear Release follow the repository-local baseline.
• GitHub Pages serves site/ through the custom domain ultrabrain-mcp.lcv.dev.
• Direct third-party uses: references in this repository's workflows must remain pinned to reviewed immutable commit SHAs. After the operator-directed retirement of actions.lock, nested actions resolve according to the official upstream action manifests; direct pins do not guarantee immutable transitive references.