OpenReyestr Service
Relevant source files
The following files were used as context for generating this wiki page:
The OpenReyestr Service is a specialized Model Context Protocol (MCP) server within the SecondLayer monorepo designed to provide access to the Unified State Register of Ukraine (NAIS). It facilitates AI-powered lookups and analysis of business entities, individual entrepreneurs (FOPs), and beneficial owners by processing large-scale open data provided by the Ukrainian government (data.gov.ua).
The service operates in a dual-mode architecture, supporting both standard MCP stdio for direct integration with AI assistants like Claude Desktop and an HTTP REST API for web-based integration. It plays a critical role in the project's legal tech capabilities by linking official state registry data to other legal modules such as court cases and legislation.
Sources: CLAUDE.md:65-68, mcp_openreyestr/QUICKSTART.md:1-5, mcp_openreyestr/package.json:2-5
Architecture and Data Flow
The OpenReyestr Service follows a structured pipeline for data ingestion, storage, and retrieval. It is designed to handle millions of records extracted from large XML datasets provided in ZIP format from the official government portal.
Data Ingestion Pipeline
The ingestion process involves downloading compressed registry files and using specialized parsers to import data into a PostgreSQL database.
The diagram shows the flow from the raw ZIP data provided by data.gov.ua through specific entity parsers into the persistent PostgreSQL storage.
Sources: mcp_openreyestr/QUICKSTART.md:28-40, mcp_openreyestr/package.json:10-14
Technical Stack
- Runtime: Node.js 20+
- Database: PostgreSQL 15+ (port 5435 in local dev, 5437 in dev environment)
- Data Format: XML (Fast-XML-Parser, sax)
- API Framework: Express.js
- Auth: Dual-auth (Bearer token and optional Google OAuth)
Sources: mcp_openreyestr/package.json:37-60, DEPLOY_DEV_FIXES.md:33-41, CLAUDE.md:73-80
MCP Tools and Functionality
The service exposes five primary tools through the MCP protocol, allowing AI models to perform structured searches and detail lookups.
| Tool Name | Purpose | Description |
|---|---|---|
openreyestr_search_entities | Entity Search | Search for businesses or entrepreneurs by name or keywords. |
openreyestr_get_entity_details | Detail Retrieval | Get full profile of a specific entity using its record ID. |
openreyestr_get_beneficiaries | Ownership Analysis | Retrieve information about beneficial owners of a legal entity. |
openreyestr_search_debtors | Debt Tracking | Cross-reference entities against the debtors registry. |
openreyestr_get_edrpou_info | EDRPOU Lookup | Direct lookup using the 8-digit identification code. |
Sources: lexwebapp/BUILD_SUMMARY.md:89-91, CLAUDE.md:104-106, mcp_openreyestr/QUICKSTART.md:67-90
API Endpoints
The HTTP mode provides RESTful access to the registry data, primarily used by the lexwebapp frontend.
Primary Endpoints
POST /api/search: Search entities with support forquery,entityType(UO, FOP, FSU), andlimit.GET /api/statistics: Returns current registry counts and import status.GET /health: Basic health check for service availability.
Interaction Sequence
The sequence illustrates a typical search request originating from the web frontend and interacting with the OpenReyestr database.
Sources: mcp_openreyestr/QUICKSTART.md:58-65, mcp_openreyestr/package.json:15-18
Configuration and Deployment
The service is highly configurable via environment variables and is deployed as a containerized service.
Environment Variables
| Variable | Description | Default/Example |
|---|---|---|
DATABASE_URL | Connection string for PostgreSQL | postgresql://openreyestr... |
HTTP_PORT | Port for the REST API | 3005 (Dev: 3004) |
OPENREYESTR_DATA_PATH | Path to the XML/ZIP source files | /path/to/OPENREYESTR |
SECONDARY_LAYER_KEYS | Authorized API keys for Bearer auth | your-api-key |
Sources: mcp_openreyestr/QUICKSTART.md:14-22, DEPLOY_DEV_FIXES.md:33-41
Deployment Contexts
- Local: Runs on port 3005/5435.
- Development (Dev): Hosted on
gate.lexapp.co.ua, port 3005, with database on 5437. - Unified Gateway: In staging, it is aggregated into a single endpoint (port 3004) with other MCP services.
Sources: DEPLOY_DEV_FIXES.md:33-41, CLAUDE.md:99-102
Data Import Scripts
Registry data is imported using specialized CLI commands defined in package.json. These scripts handle the heavy lifting of processing millions of records.
# Import all entities from a ZIP archive
npm run import:all /path/to/archive.zip
# Specific registry imports
npm run import:debtors
npm run import:entities
Note: Full imports can take 1-3 hours depending on hardware and require approximately 10-20GB of free disk space for the PostgreSQL indexes.
Sources: mcp_openreyestr/package.json:10-14, mcp_openreyestr/QUICKSTART.md:28-48
Summary
The OpenReyestr Service provides a robust bridge between official Ukrainian registry data and AI-driven legal analysis. By transforming static XML dumps into a queryable PostgreSQL database and exposing it via MCP and REST interfaces, it enables features such as automated beneficiary lookups and debtor verification within the SecondLayer ecosystem. Its architecture prioritizes performance for large datasets through the use of streaming XML parsers and optimized database indexing.