Mousecat

Mousecat is one MCP server for AI coding hosts that need structured operator interaction, governed workflow chains, live multi-agent visualization, and routed access to an AI tool ecosystem. Hosts see one tool namespace. Mousecat owns routing, skill-framework buttons, work permits, policy, credential references, connector status, and live status.

Mousecat is MPL-2.0, GZDS-governed open-source bridge code. It does not ship private Neo tools. A local ignored config can point Mousecat at a private Neo MCP server, then Mousecat discovers tools dynamically and forwards permitted calls at runtime.

Quick Start

npm test
node src/cli.mjs status
node src/cli.mjs connectors
node src/cli.mjs buttons
node src/cli.mjs mcp

For MCP hosts, start:

node src/cli.mjs mcp

Related MCP server: projscan

PR Readiness

Mousecat is AI-native and GZDS-governed. Contributions are expected to satisfy the public readiness surface before review.

npm run pr:ready

That command runs tests, GitHub classifier tests, runtime smokes against .github/mousecat.ci.config.json, governance floor, governance ceiling, doc currency, and strict hygiene. GitHub Actions runs the same PR readiness surface on push to main and on pull requests, across Node 20 and 22 on ubuntu-latest, then runs npm audit --audit-level=high. Pull requests also run chronology and PR-shape classifier gates.

CodeQL, dependency maintenance, and secret scanning are separate public security surfaces. Status checks become required once branch protection is configured on the GitHub remote.

The server exposes:

First Surfaces

Mousecat ships with source-owned skill atoms for Crucible, Mass-Assault, and Total Recall. These atoms render as buttons that hosts can place in JetBrains widgets, Claude Code or Codex panels, Cursor surfaces, and CLI views. The same registry also defines skill frameworks, work-permit profiles, upstream descriptors, tool boundaries, interaction shapes, and visualizer-safe event streams.

Private Neo Connector

Copy mousecat.config.example.json to ignored mousecat.config.json, enable connectors.neo, and point it at the local private Neo MCP server command. The checked-in example is disabled and uses placeholder paths. Use node src/cli.mjs --config <path> <command> to run a command against a specific public or local config.

node src/cli.mjs connectors
node src/cli.mjs tools neo
node src/cli.mjs resources neo
node src/cli.mjs bridge neo
node src/cli.mjs invoke neo <neo-tool-name> profileId=tool-invocation example=payload

Dynamic discovery comes from the configured MCP server's tools/list and resources/list responses. mousecat.bridge reads the public mousecat_bridge_contract_v1 resource and returns a sanitized summary with public routes, boundary classes, stale-runtime policy, and withheld-surface labels. Do not commit generated discovery output, local paths, credentials, or private tool schemas.

Source Policy

Mousecat core source is licensed under MPL-2.0. The file-level copyleft posture keeps modifications to Mousecat source files open when distributed while allowing proprietary hosts, plugins, adapters, and local/private upstreams to integrate through public contracts. Runtime transcripts, private host state, credential values, Z-Library session state, upstream caches, and generated local artifacts stay out of Git.

Read First

Read CORE.md, ARCHITECTURE.md, GOVERNANCE.md, ROADMAP.md, SESSION_STATE.md, and AGENTS.md before changing public tool names, connector semantics, permit semantics, credential policy, or skill-framework records.