System Overview
Last updated
Last updated
The SigilAI MCP server is architected as a robust, scalable, and secure platform for delivering security scanning capabilities to AI systems and developers. This document provides a high-level overview of the system architecture, its key components, and the design principles that guide its development.
The SigilAI architecture is designed to achieve the following key goals:
Modularity: Components are designed to be independent and interchangeable.
Scalability: The system can handle increasing loads and data volumes.
Reliability: High availability and fault tolerance are prioritized.
Security: Secure by design, protecting data and system integrity.
Extensibility: New scanning capabilities and tools can be easily added.
Interoperability: Seamless integration with AI platforms via MCP.
Maintainability: Clear separation of concerns for ease of updates.
Client Layer: Consists of applications that consume SigilAI's services, such as Large Language Models (LLMs), AI assistants, or developer tools. These clients interact with the SigilAI MCP Server via the Model Context Protocol.
MCP Server Layer: This is the core of the SigilAI platform.
MCP Interface: Handles incoming MCP requests (e.g., over Server-Sent Events - SSE), validates them, and manages communication with clients.
Tool Dispatcher: Routes validated requests to the appropriate scanning service based on the tool name.
Session Management: Manages client sessions, including connection and disconnection events.
Configuration Service: Provides configuration parameters to various components.
Logging & Monitoring: Captures system logs and metrics for operational insights and troubleshooting.
Security Scanning Core: Contains the specialized services that perform the actual security analysis.
URL Scanning Service: Analyzes URLs for threats.
File Scanning Service: Scans source code files for vulnerabilities.
Test Tool Service
External Dependencies & Integrations: Represents external systems and data sources that the scanning core relies on.
Security Databases: Such as URL blacklists or vulnerability databases.
Third-Party Scanning Engines: External tools like Semgrep or Snyk that are invoked by the File Scanning Service.
SigilAI's architecture adheres to industry best practices and design principles:
Each component has a well-defined responsibility. For example, the MCP Interface handles protocol-level communication, while the Scanning Services focus solely on analysis. This promotes modularity and maintainability.
While not necessarily deployed as separate microservices, the components are designed with clear boundaries, allowing for potential future decomposition into independent services if scalability demands it. This aligns with principles like Domain-Driven Design (DDD).
The interaction between layers, particularly between the MCP Server and the Scanning Core, is defined by clear APIs. This allows for independent development and testing of components.
For potentially long-running scanning tasks, asynchronous processing patterns are employed to prevent blocking the MCP server and ensure responsiveness to clients. This is crucial for handling multiple concurrent requests efficiently.
Scanning services are designed to be stateless where feasible, meaning they don't retain session information between requests. This simplifies scaling and improves fault tolerance. Any required state is managed by the Session Management component or persisted in external data stores.
Security considerations are integrated throughout the architecture:
Input Validation: Rigorous validation of all incoming data at the MCP Interface (using Zod schemas) and at each service boundary.
Least Privilege: Components operate with the minimum necessary permissions.
Secure Communication: Use of HTTPS/TLS for external communication and secure internal channels where appropriate.
Data Protection: Measures to protect sensitive data, such as scan results or user information, both in transit and at rest.
The system incorporates comprehensive logging, metrics collection, and tracing capabilities (via the Logging & Monitoring component) to ensure operational visibility and facilitate troubleshooting. This aligns with the principles of observability in modern distributed systems.
The architecture is designed to easily accommodate new scanning tools or services. The Tool Dispatcher can be updated to route requests to new services, and new services can be added to the Scanning Core without impacting existing functionality.
While the specific technology choices can evolve, a typical stack might include:
Programming Language: TypeScript/Node.js for the MCP server and scanning services, leveraging its asynchronous capabilities and rich ecosystem.
MCP Library: fastmcp for implementing the MCP server.
Web Framework: Express.js or Fastify for handling HTTP-based communication (e.g., SSE).
Data Validation: Zod for schema definition and validation.
Containerization: Docker for packaging and deploying components.
Orchestration: Kubernetes (if deployed as microservices).
Logging: Winston or Pino.
Monitoring: Prometheus, Grafana.
An LLM client sends an MCP tool_call request for scan_url to the SigilAI MCP Server's MCP Interface.
The MCP Interface validates the request and passes it to the Tool Dispatcher.
The Tool Dispatcher identifies the scan_url tool and routes the request to the URL Scanning Service.
The URL Scanning Service performs its analysis, potentially querying external Security Databases.
The URL Scanning Service returns the structured result to the Tool Dispatcher.
The Tool Dispatcher forwards the result to the MCP Interface.
The MCP Interface sends the MCP tool_result back to the LLM client.
Horizontal Scaling: The MCP Server and Scanning Services can be scaled horizontally by running multiple instances behind a load balancer.
Fault Tolerance: Redundancy can be built in at various levels. If one instance of a scanning service fails, requests can be routed to healthy instances.
Resilience: Use of patterns like circuit breakers when interacting with external dependencies to prevent cascading failures.
Database Scalability: Choice of scalable database solutions for persisting data.
This system overview provides a foundational understanding of the SigilAI MCP server's architecture. Subsequent documents in this section will delve deeper into specific architectural aspects.
Next: MCP Integration
Future Scanning Services: Placeholder for new scanning capabilities.
