Tool Registry & Discovery
Relevant source files
The following files were used as context for generating this wiki page:
The Tool Registry and Discovery system in SecondLayer provides a unified interface for accessing specialized legal AI capabilities via the Model Context Protocol (MCP). It serves as the central hub for exposing backend functionality—including court case search, legislation retrieval, document analysis, and procedural calculations—to distributed LLM clients such as Claude Desktop, ChatGPT, and the project's own web frontend.
The system aggregates tools from multiple internal MCP servers (mcp_backend, mcp_rada, and mcp_openreyestr) and organizes them into a unified gateway. This architecture allows for seamless tool discovery through standard MCP ListTools requests and execution via CallTool requests, supporting both standard I/O and remote Server-Sent Events (SSE) transports. Sources: CLAUDE.md, mcp_backend/src/index.ts:74-150
Architecture and Tool Aggregation
The discovery mechanism is built on a factory pattern that composes services into a unified API. The primary entry point for discovery is the ListToolsRequestSchema handler in the backend server, which dynamically assembles tool definitions based on the availability of sub-services and microservices. Sources: CLAUDE.md, mcp_backend/src/index.ts:76-150
Unified Gateway Structure
The platform utilizes a "Unified Gateway" (Stage environment) that aggregates 45 distinct tools:
- 36 Backend Tools: Focus on court cases, semantic search, and legal practice.
- 4 RADA Tools: Focused on parliament data (prefixed with
rada_*). - 5 OpenReyestr Tools: Focused on state registers (prefixed with
openreyestr_*).
Sources: CLAUDE.md, lexwebapp/BUILD_SUMMARY.md
Discovery Data Flow
The following diagram illustrates how the server assembles the tool list for a client discovery request.
The server checks for environment configurations (e.g., Vision credentials or Microservice URLs) before including specific tool categories in the discovery list. Sources: mcp_backend/src/index.ts:35-72, mcp_backend/src/index.ts:76-150
Tool Categories and Registration
Tools are registered in specialized modules and then aggregated in the main server class. The project defines "Enterprise Primitives" (reusable pipeline steps) and "Product Tools" (specific legal tasks). Sources: lexconfig/services_tooling_map.txt:11-25
Core Pipeline Primitives
These primitives are defined in the pipeline contracts and are essential for legal reasoning chains:
| Tool Name | Purpose | Input Context |
|---|---|---|
classify_intent | Determines legal service, task, and depth | User query |
retrieve_legal_sources | Fetches raw sources (cases/laws) | Query context |
extract_document_sections | Converts text into machine-readable sections | Raw documents |
analyze_legal_patterns | Identifies arguments and risk factors | Extracted sections |
validate_response | Checks facts/citations to prevent hallucinations | Answer + Sources |
| Sources: lexconfig/pipeline_contracts.txt:38-155 |
Specialized Tool Modules
The registry dynamically includes tools from the following handlers:
- Legislation Tools: Handles RADA-integrated legislation search and article retrieval.
- Vault Tools: Provides secure document storage and semantic search (requires Vision/OCR config).
- Due Diligence Tools: Orchestrates bulk reviews and risk scoring.
- Document Analysis (Microservice): Specialized tools like
parse_documentandcompare_documentsrouted to an external document service.
Sources: mcp_backend/src/index.ts:78-150
Tool Execution and Routing
Execution is handled via the CallToolRequestSchema handler, which acts as a router. The routing logic ensures that requests are directed to the correct service implementation or external microservice. Sources: mcp_backend/src/index.ts:153-263
Request Lifecycle
If a tool requires a service that is not configured (e.g., DOCUMENT_SERVICE_URL is missing), the registry returns a standard MCP error object. Sources: mcp_backend/src/index.ts:219-250
Discovery and Integration Endpoints
The system supports multiple discovery protocols for different client types. Sources: CLAUDE.md, lexwebapp/BUILD_SUMMARY.md, deployment/nginx/README.md
API and Transport Map
| Endpoint | Protocol | Targeted Client |
|---|---|---|
| Stdio | MCP Stdio | Claude Desktop (Local) |
/mcp | Discovery JSON | Server Discovery |
/sse | Remote MCP (SSE) | Distributed LLM Clients |
/api/tools | REST GET | Web Frontend Discovery |
/api/tools/:name | REST POST | Sync Tool Execution |
/api/tools/:name/stream | SSE POST | Async Tool Execution w/ Thinking Steps |
| Sources: CLAUDE.md, lexwebapp/BUILD_SUMMARY.md, deployment/nginx/README.md |
Integration Verification
Discovery and tool integrity are verified through integration tests that call the registry endpoints.
test('should list all available tools', async () => {
const response = await client.get('/api/tools');
expect(response.status).toBe(200);
expect(response.data.tools.length).toBeGreaterThan(30);
});
Sources: mcp_backend/src/api/__tests__/all-tools-integration.test.ts:54-60
Summary
The Tool Registry & Discovery system centralizes the complex orchestration of 45 legal AI tools into a standard MCP interface. By utilizing a modular routing architecture and a unified gateway, it enables varied clients to discover and execute high-level legal tasks—ranging from simple intent classification to complex document comparison and legislative research—while maintaining strict separation between core primitives and specialized product tools.