MCP中间件层

AI Assistant ←→ Passthrough Server ←→ Target MCP Server
                       ↓↑
                    [Hooks]

1. Request:  AI → Passthrough → Hook 1 → Hook 2 → ... → Target MCP Server
2. Response: AI ← Passthrough ← Hook 2 ← Hook 1 ← ... ← Target MCP Server

Human user: Can precisely click on files they need
LLM: Might try to read entire directory trees to "be helpful"

Guardrail Hook: Limits directory traversal depth, prevents reading 
binary files, and caps file sizes - rules that only make sense for LLMs

Standard fetch tool: "Retrieves web content"

In a research environment:
"Retrieves web content (academic sources preferred, checks Sci-Hub)"

In a corporate environment:
"Retrieves web content (internal wiki only, external sites blocked)"

Without hook:
AI: execute_sql("DROP TABLE users")

With Explain Hook:
AI: execute_sql("DROP TABLE users", reason="User requested database cleanup")

MCP Server returns: {status: "success", rowsAffected: 1523}

Audit Hook logs:
- Tool: database_query
- Action: "Bulk update customer emails"  
- Impact: 1523 records modified
- Context: "Part of migration from old email domain"
- Risk level: High (bulk data modification)

git clone https://github.com/civicteam/mcp-hooks.git
cd mcp-hooks
pnpm install
pnpm build

# Terminal 1: Start the fetch-docs MCP server
cd packages/fetch-docs
pnpm start

# Terminal 2: Start the audit hook
cd packages/audit-hook
pnpm start

# Terminal 3: Start the passthrough server
cd packages/passthrough-mcp-server
export TARGET_SERVER_URL="http://localhost:33005"
export HOOKS="http://localhost:33004"
pnpm start

cd test
./test.sh simple-log-passthrough.json  # See basic logging in action
./test.sh audit-passthrough.json       # Test audit trail functionality
./test.sh guardrail-passthrough.json   # Test security filtering
./test.sh playwright-tokensaver-proxy.json # Test token-efficient Playwright wrapper

mkdir packages/my-hook
cd packages/my-hook
pnpm init

pnpm add @civic/hook-common @trpc/server

import { AbstractHook, createHookRouter, ToolCallRequestHookResult } from "@civic/hook-common";
import { createHTTPServer } from "@trpc/server/adapters/standalone";
import type { CallToolRequest } from "@modelcontextprotocol/sdk/types.js";

class MyHook extends AbstractHook {
  get name(): string {
    return "my-hook";
  }

  async processCallToolRequest(request: CallToolRequest): Promise<ToolCallRequestHookResult> {
    // Your logic here
    console.log(`Processing: ${toolCall.params.name}`);
    
    // Continue with the request
    return {
      resultType: "continue",
      request: toolCall
    };
  }
}

// Start the server
const hook = new MyHook();
const router = createHookRouter(hook);
const server = createHTTPServer({ router, createContext: () => ({}) });
server.listen(33007);

export HOOKS="http://localhost:33007"
pnpm start

export HOOKS="http://localhost:33004,http://localhost:33005,http://localhost:33006"

mcp-hooks/
├── packages/
│   ├── passthrough-mcp-server/   # Main proxy server
│   ├── hook-common/              # Shared types and utilities
│   ├── audit-hook/               # Example: Logging hook
│   ├── guardrail-hook/           # Example: Security hook
│   ├── simple-log-hook/          # Example: Minimal hook
│   ├── explain-hook/             # Example: Transparency hook
│   ├── playwright-tokensaver-proxy/ # Example: Token-efficient Playwright wrapper
│   ├── custom-description-hook/  # Example: Transform hook
│   ├── rate-limit-hook/          # Example: Rate limiting hook
│   ├── local-tools-hook/         # Example: Programmatic tools hook
│   ├── fetch-docs/               # Test MCP server
│   └── whoami-server/            # Test auth server
├── test/                         # Test configurations
└── docs/                         # Additional documentation

interface Hook {
  name: string;
  processCallToolRequest?(request: CallToolRequest): Promise<ToolCallRequestHookResult>;
  processCallToolResult?(response: CallToolResult, originalCallToolRequest: CallToolRequest): Promise<ToolCallResponseHookResult>;
  processToolsList?(request: ListToolsRequest): Promise<ListToolsRequestHookResult>;
  processListToolsResult?(response: ListToolsResult, originalRequest: ListToolsRequest): Promise<ListToolsResponseHookResult>;
  processToolCallTransportError?(error: unknown, originalCallToolRequest: CallToolRequest): Promise<ToolCallTransportErrorHookResult>;
  processToolsListTransportError?(error: unknown, originalRequest: ListToolsRequest): Promise<ListToolsTransportErrorHookResult>;
}

pnpm install          # Install dependencies
pnpm build           # Build all packages
pnpm test            # Run tests
pnpm lint            # Check code style
pnpm dev             # Start in watch mode