@civic/mcp-tools

What is @civic/mcp-tools?

A middleware layer for the Model Context Protocol (MCP) that enables monitoring, validation, and transformation of AI tool interactions. It introduces a “passthrough server” that sits between the AI assistant and the target MCP server, routing all requests through a configurable chain of hooks. Designed for developers who need security, auditing, control, and customization on top of MCP.

How to use @civic/mcp-tools?

Clone the repository, install dependencies with pnpm install, and build with pnpm build. Start a target MCP server (e.g., fetch-docs), start one or more hook servers (e.g., audit-hook), then run the passthrough server with environment variables TARGET_SERVER_URL and HOOKS. Ready-to-run test configurations are available in the test/ directory.

Key features of @civic/mcp-tools

• Intercepts and routes all MCP tool requests through a hook chain
• Hooks can inspect, modify, approve, reject, or transform requests and responses
• Supports chaining multiple hooks in order
• Includes ready‑to‑use hooks: audit, guardrail, explain, rate‑limit, custom‑description, local‑tools, and token‑saver
• Fully typed, built with TypeScript, tRPC, and fastMCP
• Allows easy creation of custom hooks via the AbstractHook base class

Use cases of @civic/mcp-tools

• Add LLM‑specific guardrails (e.g., limit directory traversal, block binary files)
• Provide context‑dependent tool descriptions (e.g., different wording for research vs. corporate)
• Force the AI to explain tool use by adding a required “reason” parameter
• Build semantic audit trails with compliance logging for every tool call
• Enforce rate limits per user on tool calls

FAQ from @civic/mcp-tools

What is MCP and why does it need hooks?

MCP is a protocol that lets AI assistants (like Claude) interact with external tools. Without hooks, there is no way to enforce security, audit actions, or customize behavior for LLM‑specific needs. Hooks add a middleware layer to address these gaps.

How does the passthrough server work?

The passthrough server intercepts each request from the AI, processes it through a chain of hooks (each can inspect, modify, approve, or reject), then forwards approved requests to the target MCP server. Responses travel back through the hook chain in reverse order.

What hooks are included?

The monorepo provides audit‑hook, guardrail‑hook, simple‑log‑hook, explain‑hook, playwright‑tokensaver‑proxy, custom‑description‑hook, rate‑limit‑hook, and local‑tools‑hook. Each can be used independently or chained together.

How do I create my own hook?

Create a new package, install @civic/hook-common and @trpc/server, then extend the AbstractHook class and implement the desired hook methods (e.g., processCallToolRequest). Start the hook as a tRPC HTTP server.

What transport and environment variables are supported?

The passthrough server can communicate with the target MCP server via httpStream, sse, or stdio (set via TARGET_SERVER_TRANSPORT). Key env vars: PORT (default 34000), TARGET_SERVER_URL, HOOKS (comma‑separated URLs).