LibroSynth MCP Architecture

The LibroSynth MCP Server is a Model Context Protocol interface that exposes the LibroSynth v3.0 AI research platform to Claude Code and Claude Desktop. It bridges Claude's tool-calling capabilities with LibroSynth's core intelligence services: cross-domain knowledge synthesis, causal analysis, meta-learning optimization, autonomous self-improvement, and multi-dimensional intelligence tracking.

The server runs as a Node.js process communicating over stdio (MCP transport) while simultaneously proxying all tool calls to the LibroSynth API Gateway via HTTP. It provides 7 MCP tools that map directly to the platform's REST API endpoints, enabling AI agents to orchestrate evolutionary cycles, synthesize knowledge from books, optimize learning strategies, and predict intelligence trajectories.

Key insight: This is a thin translation layer. It contains no business logic itself -- all intelligence operations are delegated to the LibroSynth microservice cluster behind the API Gateway.

MCP Tools

Transport

stdio

Runtime

Node.js 20

Upstream API

FastAPI :8000

Source Files

Health Port

3000

2. Runtime Architecture

Diagram A -- Runtime Request Flow

Request Flow Narrative

Claude Code sends a tool call (e.g. synthesize_books) over the stdio transport to the MCP Server process.
The LibroSynth MCP Server receives the call via @modelcontextprotocol/sdk, matches it in a switch statement, and translates it to an HTTP request using axios.
The HTTP request hits the API Gateway (FastAPI on port 8000), which routes to the appropriate microservice endpoint.
The relevant microservice (Orchestrator, Knowledge Synthesis, Meta-Learning, or Intelligence Metrics) processes the request, interacting with PostgreSQL for state and RabbitMQ for async tasks.
The response propagates back: microservice -> API Gateway -> MCP Server -> Claude Code (as JSON text content).

3. Public Interfaces (MCP Tools)

The server exposes 7 MCP tools. All tools return JSON-formatted text content. On error, responses include isError: true with the error message.

Tool Name	Description	Required Parameters	Upstream Endpoint
`execute_cycle`	Execute an evolutionary cycle (1-4). Each cycle is a 21-day self-improvement period targeting specific intelligence milestones.	`cycle_number` (number)	`POST /api/v1/orchestration/cycles`
`get_intelligence`	Get current intelligence snapshot with all 10 dimensions (knowledge extraction, pattern recognition, synthesis capability, learning efficiency, adaptation speed, innovation capacity, meta-cognition, reasoning depth, knowledge retention, transfer learning).	None	`GET /api/v1/intelligence/snapshot`
`synthesize_books`	Synthesize knowledge from multiple books using transformer-based neural synthesis. Supports 7 synthesis modes for different analytical approaches.	`books` (array of objects)	`POST /api/v1/synthesis/multi-book`
`optimize_strategy`	Optimize learning strategy based on context (book complexity, length, topics). Uses neural meta-learner to select optimal approach.	`context` (object)	`POST /api/v1/meta-learning/optimize-strategy`
`analyze_performance`	Analyze learning performance from a completed session, providing insights on strategy effectiveness and improvement areas.	`learning_session` (object)	`POST /api/v1/meta-learning/analyze`
`predict_trajectory`	Predict intelligence evolution trajectory over a given time horizon. Default horizon is 90 days.	None (optional: `time_horizon_days`)	`GET /api/v1/intelligence/trajectory`
`run_optimization`	Run autonomous optimization. Supports scopes: HYPERPARAMETERS, MODEL_ARCHITECTURE, ALGORITHM_SELECTION. Strategies: BAYESIAN, EVOLUTIONARY, GRADIENT_DESCENT, GENETIC_ALGORITHM.	`scope` (string), `strategy` (string)	`POST /api/v1/optimization/run`

Synthesis Modes

The synthesize_books tool supports the following modes via the optional mode parameter:

CROSS_DOMAIN

Default. Finds connections across different fields of knowledge.

CAUSAL

Identifies causal relationships and chains of reasoning.

EMERGENT

Discovers emergent insights not present in individual sources.

CONTRASTIVE

Contrasts opposing viewpoints and highlights tensions.

TEMPORAL

Analyzes evolution of ideas over time.

ANALOGICAL

Finds structural parallels between different domains.

HIERARCHICAL

Builds hierarchical knowledge structures from flat inputs.

Health Endpoint

In addition to the MCP stdio interface, the server exposes an HTTP health endpoint on port 3000:

GET http://localhost:3000/health
Response: { "status": "healthy", "version": "3.0.0" }

This endpoint is used by Docker's HEALTHCHECK for container orchestration.

4. Repository Structure

docker/mcp-server/                    # MCP server root (within LibroSynth repo)
  Dockerfile                            # Multi-stage build (node:20-alpine)
  package.json                          # NPM manifest, 3 runtime deps
  src/
    index.js                            # Complete server implementation (298 lines)
                                        #   - Express health server (:3000)
                                        #   - MCP Server (stdio transport)
                                        #   - 7 tool handlers (switch/case)
                                        #   - Tool schema definitions
                                        #   - Graceful shutdown handlers

Component Classification

Component	Classification	Role
`src/index.js`	Primary	Complete MCP server: transport setup, tool dispatch, health endpoint, error handling
`Dockerfile`	Secondary	Multi-stage Docker build with Alpine base for minimal image size
`package.json`	Auxiliary	Dependency manifest and entry point configuration

Single-file architecture: The entire MCP server is implemented in one file (src/index.js, 298 lines). This is appropriate for a thin proxy layer -- it contains no business logic, only tool dispatch and HTTP forwarding.

5. Deployment

Container Configuration

Parameter	Value
Container name	`librosynth-mcp-server`
Base image	`node:20-alpine` (multi-stage)
Exposed port	3000 (health check only)
MCP transport	stdio (stdin/stdout)
Docker network	`librosynth_librosynth-backend`
Health check	`wget http://localhost:3000/health` every 30s
Build context	LibroSynth repo root (paths reference `docker/mcp-server/`)

Environment Variables

Variable	Default	Purpose
`API_BASE_URL`	`http://api-gateway:8000`	LibroSynth API Gateway URL (Docker DNS)
`PORT`	`3000`	Express health endpoint port

Docker Compose Integration

The MCP server is part of the LibroSynth stack at /home/rod/_rod/_librosynth/docker-compose.yml. It runs on the librosynth-backend network alongside 10 other containers:

# Stack overview (11 containers)
api-gateway        # FastAPI REST API (:8000)
orchestrator       # Evolutionary cycle management
knowledge-synthesis # Transformer-based book synthesis
meta-learning      # Neural meta-learner
intelligence-metrics # 10-dimension intelligence tracking
optimization       # Autonomous hyperparameter optimization
postgres           # PostgreSQL (:5433)
rabbitmq           # RabbitMQ (:5672/15672)
minio              # S3-compatible object storage (:9002)
web-dashboard      # React dashboard (:3002)
mcp-server         # This server (:3000 health, stdio MCP)

Claude Code Configuration

To connect Claude Code to this MCP server, add to ~/.claude/.mcp.json:

{
  "librosynth": {
    "command": "docker",
    "args": ["exec", "-i", "librosynth-mcp-server", "node", "src/index.js"],
    "transportType": "stdio"
  }
}

Signals and Shutdown

The server handles SIGINT and SIGTERM for graceful shutdown. Both signals trigger a clean process.exit(0).

6. Dependencies

Runtime Dependencies

Package	Version	Purpose
`@modelcontextprotocol/sdk`	^0.5.0	MCP protocol implementation: Server class, StdioServerTransport, request schemas
`axios`	^1.6.2	HTTP client for proxying tool calls to the LibroSynth API Gateway
`express`	^4.18.2	Lightweight HTTP server for the /health endpoint (Docker HEALTHCHECK)

Dev Dependencies

Package	Version	Purpose
`nodemon`	^3.0.2	Auto-restart during development (`npm run dev`)

System Requirements

Requirement	Version	Notes
Node.js	>= 18.0.0	Specified in `engines` field; Dockerfile uses Node 20 Alpine
Docker	20.10+	Multi-stage build support required
LibroSynth API	v3.0	API Gateway must be running on the same Docker network

Upstream Service Dependencies

The MCP server has a hard runtime dependency on the LibroSynth API Gateway. If the gateway is unreachable, all 7 tools will return error responses. The health endpoint (/health) will still respond -- it only checks the MCP server process itself, not upstream connectivity.

7. Constraints & Risks

Item	Severity	Description
No authentication	MEDIUM	The MCP server has no authentication layer. It relies on stdio transport (local process) and Docker network isolation for security. The Express health endpoint on port 3000 is also unauthenticated.
No request validation	MEDIUM	Tool arguments are forwarded directly to the API Gateway without validation. Invalid inputs will produce upstream error responses rather than early rejections.
Single-process architecture	LOW	Both the Express health server and the MCP stdio server run in the same Node.js process. A crash in either will take down both. Acceptable for the current scale.
No retry logic	LOW	HTTP calls to the API Gateway use axios with no retry or circuit-breaker configuration. Transient failures will propagate as errors to the caller.
SDK version pinning	LOW	The MCP SDK is pinned to ^0.5.0. The MCP protocol is evolving rapidly; major version changes may require tool schema updates.
No test suite	MEDIUM	No unit or integration tests exist for the MCP server. Changes to tool schemas or upstream API contracts could break silently.

Generated by /repo-architecture v2.0.0 on 2026-03-22. This document is auto-generated -- regenerate after significant changes.