mizcausevic-dev/mcp-kinetic-gain

Purpose and principal workflow

mcp-kinetic-gain exposes Kinetic Gain Protocol Suite documents and policy checks as MCP tools, with a separate CLI mode for validating local JSON files. An MCP-compatible client initiates the main workflow over stdio: the server advertises its tools, dispatches a requested tool to its handler, and returns the handler’s result. Depending on the tool, the handler may validate supplied JSON, fetch a remote document, or analyze related artifacts.

Components

MCP entry and tool surface

• MCP server and entry point — src/server.ts: Builds the MCP server, registers tool-list and tool-call handlers, connects the stdio transport, and dispatches calls to domain handlers; it also hands off CLI subcommands.

• Tool catalog — src/tools.ts: Defines the tool names, descriptions, and input schemas that the server advertises to clients.

Suite document and policy handlers

• AEO and provenance handlers — src/handlers/aeo.ts: Provides AEO declaration tools; the README also documents Prompt Provenance tools, whose implementation is not shown in the sample.

• Agent, evidence, and tool-card handlers — src/handlers/agent-card.ts: Handles agent-card tools; AI Evidence and MCP Tool Card tools are also documented, but their handler excerpts were not sampled.

• Tutor and classroom policy handlers — src/handlers/classroom-aup.ts: Validates, fetches, and inspects Classroom AI AUPs and checks an AUP against a Student AI Disclosure; tutor and disclosure handlers are present in the tree, but their implementations were not sampled.

• Clinical disclosure handler — src/handlers/clinical-ai.ts: Provides the Clinical AI Card tool family, documented in the README; implementation details were not sampled.

• Incident analysis handler — src/handlers/ai-incident.ts: Fetches and validates incident cards and provides incident-index, affected-document, and remediation analysis.

• Procurement decision handler — src/handlers/decision-card.ts: Loads Decision Cards from inline JSON or a URL, validates and inspects them, infers status, creates policy bundles, and checks signatures.

• Claims decision handler — src/handlers/claims-card.ts: Validates and inspects AI Claims Decision Cards and computes canonical hashes or predecessor-chain fields.

• DefenseTech policy checks — src/handlers/defensetech.ts: Applies DefenseTech vault-resolution and audit-invariant checks, including DFARS timing, CUI, ITAR, event classification, and cross-binding checks.

Integrity, audit, and shared support

• Attestation and audit-event tools — src/handlers/attestation.ts: Provides the attestation tool family documented in the README; its implementation was not sampled.

• Audit-event composition and verification — src/handlers/audit-event.ts: Composes governance events and verifies event structure and hash chains locally.

• Live audit-stream client — src/handlers/audit-stream-live.ts: Provides live audit-stream tools documented in the README; the sampled source does not establish their exact request behavior.

• Document schemas — src/schemas.ts: Holds the schemas used to validate Suite documents; the CLI documentation says it selects a matching schema based on each document’s version.

• Shared fetch and formatting utilities — src/common.ts: Supplies shared helpers, including guarded HTTP fetching, response-size handling, hashing, and JSON formatting.

CLI

• Local JSON validator — src/cli.ts: Expands file patterns, reads and parses JSON, validates documents, and reports results; when no CLI subcommand is handled, control returns to the MCP entry point.

External participants

• MCP-compatible client — null: External caller that connects to the server over stdio and requests tool discovery or execution.

• Remote Suite-document hosts — null: External origins from which fetch-capable tools may retrieve documents.

• audit-stream-py service — null: External service named by the README as the target for live audit-stream operations.

• CLI user and local files — null: External initiator and input source for validation subcommands.

Relationships

• MCP-compatible client -> MCP server and entry point: launches or connects to the stdio MCP server and sends protocol requests.

• MCP server and entry point -> Tool catalog: uses the catalog to answer tool-list requests and identify callable tools.

• MCP server and entry point -> Suite document and policy handlers: dispatches matching tool calls to handlers; the server excerpt shows imports and awaited handler results.

• Suite document and policy handlers -> MCP server and entry point: return formatted results that the server wraps as MCP text content.

• Suite document and policy handlers -> Remote Suite-document hosts: fetch document content for URL-based tools; the sampled decision-card, incident, and AUP handlers call shared fetch helpers.

• Suite document and policy handlers -> Document schemas: parse and validate documents; this is explicit for the sampled Decision Card and AUP handlers.

• Suite document and policy handlers -> Shared fetch and formatting utilities: use shared fetching and formatting helpers; the sampled domain handlers import them.

• MCP server and entry point -> Local JSON validator: delegates CLI-mode argument handling; the CLI returns “not handled” when it should proceed as an MCP server.

• CLI user and local files -> Local JSON validator: supplies command arguments and files or glob patterns for validation.

• Local JSON validator -> Document schemas: selects a schema for each recognized document and validates it, as documented in the CLI source.

• MCP server and entry point -> Audit-event composition and verification: dispatches the local audit composition and verification tools through its handler registry.

• Audit-event composition and verification -> MCP server and entry point: returns composed events or verification results for the server to deliver.

• MCP server and entry point -> Live audit-stream client: dispatches live audit-stream tool calls through its handler registry.

• Live audit-stream client -> audit-stream-py service: performs live operations as documented by the README; exact HTTP methods and payload flow are not established by the sampled source.

Coverage limits

Several handler files are present in the tree and tool families are documented, but their implementations were not sampled, so their internal validation rules and call wiring are not described. The live audit-stream handler’s concrete network behavior and the MCP SDK’s internal transport mechanics could not be established from the excerpts.