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 required ci-verify gate on push to main and on pull requests, then runs npm audit --audit-level=high. Pull requests also run chronology and PR-shape classifier gates, and CI uploads structured PR classification observations for review.

CodeQL, dependency maintenance, secret scanning, Node 20 compatibility, package dry runs, and read-only PR outcome observation are separate public governance/security surfaces. Protected checks are ci-verify, node-20-compat, dependency-scan, secret-scan, and codeql.

The server exposes:

First Surfaces

Mousecat ships a generic operator-widget facade plus source-owned skill atoms for compatibility with existing governed workflows. Hosts can bind to widget controls, structured interaction shapes, and visualizer-safe event streams without knowing private workflow names. The same registry also defines skill frameworks, work-permit profiles, upstream descriptors, tool boundaries, and route policy.

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.