This document provides comprehensive TypeScript API documentation for the Argos. It covers all interfaces, types, classes, and functions available for developers working with or extending the server.
Describes the source as of v6.2.0 . These are
the internal types and classes of the server, for anyone reading or extending
it. They are not a supported import surface: the package publishes dist/ but
declares no types entry and no exports map, so names here can change without
a major version.
For the interface that is stable, see the MCP Tools Reference: the tools, their arguments and their responses are what a client depends on.
Coverage figures are deliberately not quoted here, because a number written into
a document is wrong the week after. Run npm run test:coverage for the current
state.
- Core Classes
- Database Types
- MCP Protocol Types
- Security Types
- SSH Tunnel Types
- Configuration Types
- Error Types
- Utility Functions
- Constants
- Usage Examples
Main server class that orchestrates all operations.
export class SQLMCPServer extends EventEmitter {
constructor();
// Lifecycle methods
initialize(configPath?: string): Promise<void>;
run(): Promise<void>;
cleanup(): Promise<void>;
// MCP handlers (registered with the SDK for tools/list and tools/call)
listTools(): { tools: MCPTool[] };
callTool(name: string, args: Record<string, unknown> | undefined): Promise<{ content: Array<{ type: 'text'; text: string }>; isError: boolean }>;
// Database operations
testConnection(database: string): Promise<TestConnectionResult>;
// Events emitted
on(event: 'initialized', listener: () => void): this;
on(event: 'cleanup', listener: () => void): this;
on(event: 'error', listener: (error: Error) => void): this;
}Manages database connections and connection pooling.
export class ConnectionManager extends EventEmitter {
constructor(sshTunnelManager: EnhancedSSHTunnelManager, metrics?: MetricsManager, queryCache?: QueryCache);
// Connection management
initialize(databases: Record<string, DatabaseConfig>): void;
getConnection(database: string): Promise<DatabaseConnection | null>;
closeConnection(database: string): Promise<void>;
closeAllConnections(): Promise<void>;
// Query execution
executeQuery(database: string, query: string, params?: unknown[]): Promise<QueryResult>;
executeBatch(database: string, queries: Array<{query: string; params?: unknown[]; label?: string}>, transaction?: boolean): Promise<BatchResult>;
analyzePerformance(database: string, query: string): Promise<{
executionTime: number;
explainTime: number;
rowCount: number;
columnCount: number;
executionPlan: string;
recommendations: string;
}>;
// Events emitted
on(event: 'connected', listener: (database: string) => void): this;
on(event: 'disconnected', listener: (database: string) => void): this;
on(event: 'error', listener: (error: Error, database?: string) => void): this;
}Handles query validation and security enforcement.
export class SecurityManager extends EventEmitter {
constructor(config?: SecurityManagerConfig);
// Initialization
initialize(config: ParsedServerConfig): void;
// Validation: databases with select_only = true use the first, the rest the second
validateSelectOnlyQuery(query: string, dbType?: string): SecurityValidation;
validateAnyQuery(query: string, dbType?: string): SecurityValidation;
analyzeQueryComplexity(query: string): QueryComplexityAnalysis;
// Events emitted
on(event: 'initialized', listener: (config: ParsedServerConfig) => void): this;
}Manages database schema caching and retrieval.
export class SchemaManager extends EventEmitter {
constructor(connectionManager: ConnectionManager, schemaPath?: string);
// Initialization
initialize(): Promise<void>;
// Schema operations
hasSchema(database: string): boolean;
getSchema(database: string): DatabaseSchema | null;
captureSchema(database: string, config: DatabaseConfig): Promise<DatabaseSchema>;
refreshSchema(database: string): Promise<DatabaseSchema>;
generateSchemaContext(database: string, table?: string): string;
// Events emitted
on(event: 'schema-cached', listener: (database: string) => void): this;
on(event: 'schema-refreshed', listener: (database: string) => void): this;
}Manages SSH tunnels for secure database connections.
export class EnhancedSSHTunnelManager extends EventEmitter {
constructor();
// Initialization
initialize(): Promise<void>;
// Tunnel management
createTunnel(dbName: string, options: SSHTunnelCreateOptions): Promise<SSHTunnelInfo>;
createEnhancedTunnel(dbName: string, options: EnhancedTunnelOptions): Promise<EnhancedTunnelInfo>;
hasTunnel(dbName: string): boolean;
getTunnel(dbName: string): SSHTunnelInfo | undefined;
closeTunnel(dbName: string): Promise<void>;
closeAllTunnels(): Promise<void>;
// Status
isConnected(dbName: string): boolean;
getTunnelStatus(dbName: string): SSHTunnelStatusInfo | undefined;
}The class is named EnhancedSSHTunnelManager; there is no SSHTunnelManager.
The getters return undefined rather than null for an unknown database.
Configuration for a database connection.
export interface DatabaseConfig {
type: DatabaseType;
select_only: boolean;
// Connection details (not required for SQLite)
host?: string;
port?: number;
database?: string;
username?: string;
password?: string;
// SQLite specific
file?: string;
// Connection options
ssl?: boolean;
timeout?: number;
// SSH tunnel configuration
ssh_host?: string;
ssh_port?: number;
ssh_username?: string;
ssh_password?: string;
ssh_private_key?: string;
ssh_passphrase?: string;
// MCP configuration management
mcp_configurable?: boolean;
}Supported database types.
export type DatabaseType = 'mysql' | 'postgresql' | 'postgres' | 'sqlite' | 'mssql' | 'sqlserver';
export type DatabaseTypeString = string & DatabaseType;Result of a database query execution.
export interface QueryResult {
rows: Record<string, any>[];
fields: string[];
rowCount: number;
executionTime?: number;
truncated?: boolean;
}Complete schema information for a database.
export interface DatabaseSchema {
database: string;
type: DatabaseTypeString;
captured_at: string;
tables: Record<string, TableInfo>;
views: Record<string, TableInfo>;
summary: {
table_count: number;
view_count: number;
total_columns: number;
};
}
export interface TableInfo {
name: string;
type: string;
comment?: string;
columns: ColumnInfo[];
}
export interface ColumnInfo {
name: string;
type: string;
nullable: boolean;
default: unknown;
max_length?: number | null;
precision?: number | null;
scale?: number | null;
comment?: string;
key?: string;
extra?: string;
}Two things to note about what schema capture returns, because both are easy to assume otherwise:
- Columns are an array, not a map.
TableInfo.columnsis ordered as the database returned it, and each entry carries its ownname. - Relationships and indexes are not captured. There is no foreign-key or
index metadata in the schema, on any adapter.
ColumnInfo.keycarries whatever the driver reports for the column (MySQL'sCOLUMN_KEY, for instance), which is the closest thing available. To reason about relationships, query the database's own catalogue.
Views are described with the same TableInfo shape as tables and are
distinguished by the type field.
Result of batch query execution.
export interface BatchResult {
results: BatchResultItem[];
totalExecutionTime: number;
successCount: number;
failureCount: number;
transactionUsed?: boolean;
}
export interface BatchResultItem {
index: number;
label?: string;
query?: string;
success: boolean;
data?: QueryResult;
error?: string;
}The JSON-RPC request and response envelopes come from the MCP SDK.
The tool list served for tools/list.
export function getToolDefinitions(): Array<{
name: string;
description: string;
inputSchema: { type: 'object'; properties: Record<string, unknown>; required?: string[] };
}>;
export interface MCPToolParameter {
type: string;
description?: string;
enum?: string[];
items?: MCPToolParameter;
default?: unknown;
}The definitions are plain object literals in src/tools/tool-definitions.ts and
their type is inferred rather than declared, so there is no MCPTool interface
to import. MCPToolParameter describes the shape of one property inside an
inputSchema and is the only part of this declared as a named type.
Specific input argument types for each tool.
export interface SQLQueryArgs {
database: string;
query: string;
params?: string[];
}
export interface SQLBatchQueryArgs {
database: string;
queries: Array<{ query: string; params?: string[]; label?: string }>;
transaction?: boolean;
}
export interface SQLAnalyzePerformanceArgs {
database: string;
query: string;
}
export interface SQLGetSchemaArgs {
database: string;
table?: string;
}
export interface SQLTestConnectionArgs {
database: string;
}
export interface SQLRefreshSchemaArgs {
database: string;
}The config-management tools (sql_add_database, sql_update_database,
sql_remove_database, sql_get_config, sql_set_mcp_configurable) and
sql_list_databases have no declared argument interfaces. Their handlers take
Record<string, unknown> and read the fields they need, so the authoritative
description of what each accepts is the inputSchema in
src/tools/tool-definitions.ts and the
MCP Tools Reference.
Tool response structure.
export interface MCPToolResponse {
content: MCPToolContent[];
isError?: boolean;
_meta: {
progressToken: string | null;
};
}
export interface MCPToolContent {
type: 'text' | 'image' | 'resource';
text?: string;
data?: string;
mimeType?: string;
}Result of query security validation.
export interface SecurityValidation {
allowed: boolean;
reason?: string;
confidence: number;
blockedCommand?: string;
}Analysis of query complexity and performance characteristics.
export interface QueryComplexityAnalysis {
score: number;
factors: string[];
joinCount: number;
subqueryCount: number;
unionCount: number;
groupByCount: number;
windowFuncCount: number;
risk_level: ComplexityRiskLevel;
}
export type ComplexityRiskLevel = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
### SecurityConfig
Security configuration settings.
```typescript
export interface SecurityConfig {
max_joins: number;
max_subqueries: number;
max_unions: number;
max_group_bys: number;
max_complexity_score: number;
max_query_length: number;
}
Options for creating SSH tunnels.
export interface SSHTunnelCreateOptions {
sshConfig: SSHConnectionConfig;
forwardConfig: SSHForwardConfig;
}
export interface SSHConnectionConfig {
host: string;
port: number;
username: string;
password?: string;
privateKey?: string;
passphrase?: string;
timeout?: number;
}
export interface SSHForwardConfig {
sourceHost: string;
sourcePort: number;
destinationHost: string;
destinationPort: number;
}Information about an active SSH tunnel.
export interface SSHTunnelInfo {
database: string;
localPort: number;
remoteHost: string;
remotePort: number;
sshHost: string;
sshPort: number;
status: SSHTunnelStatus;
createdAt: Date;
lastUsed?: Date;
}
export type SSHTunnelStatus =
| 'connecting'
| 'connected'
| 'error'
| 'disconnected'
| 'reconnecting';Complete server configuration after parsing.
export interface ParsedServerConfig {
databases: Record<string, DatabaseConfig>;
security?: SecurityConfig;
extension?: ExtensionConfig;
}
export interface ExtensionConfig {
max_rows: number;
max_batch_size: number;
query_timeout: number;
}Custom error classes with specific error codes.
export class SQLMCPError extends Error {
_code: string;
_details?: Record<string, unknown>;
constructor(message: string, code: string, details?: Record<string, unknown>);
}
export class SecurityViolationError extends SQLMCPError {
constructor(message: string, details?: Record<string, any>);
}
export class ConnectionError extends SQLMCPError {
constructor(message: string, details?: Record<string, any>);
}Result of database connection testing.
export interface TestConnectionResult {
success: boolean;
database: string;
message?: string;
error?: string;
ssh_tunnel: boolean;
select_only_mode: boolean;
schema_captured: boolean;
schema_info?: {
table_count: number;
view_count: number;
total_columns: number;
};
}Functions to check types at runtime.
// Redaction config guards (src/types/database.ts)
export function isValidRedactionType(value: string): value is RedactionType;
// MCP guards (src/types/mcp.ts)
export function isSQLQueryArgs(args: unknown): args is SQLQueryArgs;
export function isSQLBatchQueryArgs(args: unknown): args is SQLBatchQueryArgs;
export function isSQLGetSchemaArgs(args: unknown): args is SQLGetSchemaArgs;
export function isSQLTestConnectionArgs(args: unknown): args is SQLTestConnectionArgs;
// SSH (src/types/ssh.ts)
export function validateSSHConfig(config: SSHConnectionConfig): SSHTunnelValidationResult;Helper functions for configuration management.
// src/database/adapters/AdapterFactory.ts
AdapterFactory.getRequiredFields(type: DatabaseTypeString, config?: DatabaseConfig): string[];Default configuration values.
export const DEFAULT_SECURITY_CONFIG: SecurityConfig = {
max_joins: 10,
max_subqueries: 5,
max_unions: 3,
max_group_bys: 5,
max_complexity_score: 100,
max_query_length: 10000
};
export const DEFAULT_EXTENSION_CONFIG: ExtensionConfig = {
max_rows: 1000,
max_batch_size: 10,
query_timeout: 30000
};
export const DEFAULT_DATABASE_PORTS: Record<string, number> = {
mysql: 3306,
postgresql: 5432,
postgres: 5432,
mssql: 1433,
sqlserver: 1433
};
export const DEFAULT_CONNECTION_TIMEOUT = 30000;
export const DEFAULT_SSH_PORT = 22;Server and protocol version constants.
export const MCP_PROTOCOL_VERSION = '2025-06-18';
export const SERVER_VERSION = '2.3.1';
export const SERVER_NAME = 'argos';Arrays of valid enum values.
export const DATABASE_TYPES = ['mysql', 'postgresql', 'postgres', 'sqlite', 'mssql', 'sqlserver'] as const;
export const COMPLEXITY_RISK_LEVELS = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'] as const;
export const TOKEN_TYPES = ['KEYWORD', 'IDENTIFIER', 'STRING', 'OPERATOR', 'UNKNOWN'] as const;
export const LOG_SEVERITIES = ['INFO', 'WARNING', 'ERROR', 'CRITICAL'] as const;
export const SSH_AUTH_METHODS = ['password', 'privateKey', 'agent'] as const;
export const SSH_TUNNEL_STATUSES = ['connecting', 'connected', 'error', 'disconnected', 'reconnecting'] as const;import { SQLMCPServer } from '../../src/classes/SQLMCPServer.js';
import type { DatabaseConfig } from '../../src/types/index.js';
const server = new SQLMCPServer();
// Event handling
server.on('initialized', () => {
console.log('Server initialized successfully');
});
server.on('error', (error) => {
console.error('Server error:', error);
});
// Initialize and run
async function startServer() {
try {
await server.initialize('./config.ini');
await server.run();
} catch (error) {
console.error('Failed to start server:', error);
}
}
startServer();import { SecurityManager } from '../../src/classes/SecurityManager.js';
import type { SecurityValidation } from '../../src/types/index.js';
class CustomSecurityManager extends SecurityManager {
validateCustomRule(query: string): SecurityValidation {
if (/CUSTOM_FORBIDDEN_PATTERN/.test(query)) {
return {
allowed: false,
reason: 'Custom forbidden pattern detected',
blockedCommand: 'CUSTOM_PATTERN',
confidence: 1.0,
};
}
return { allowed: true, confidence: 1.0 };
}
}confidence is required on a SecurityValidation, and the field naming the
offending statement is blockedCommand.
import { DEFAULT_DATABASE_PORTS } from '../../src/types/index.js';
import { AdapterFactory } from '../../src/database/adapters/AdapterFactory.js';
import type { DatabaseConfig } from '../../src/types/index.js';
function createDatabaseConfig(rawConfig: any): DatabaseConfig {
// Check required fields
const required = AdapterFactory.getRequiredFields(rawConfig.type);
const missing = required.filter((field) => !rawConfig[field]);
if (missing.length > 0) {
throw new Error(`Missing required fields: ${missing.join(', ')}`);
}
return {
type: rawConfig.type,
host: rawConfig.host,
port: parseInt(rawConfig.port) || DEFAULT_DATABASE_PORTS[rawConfig.type],
database: rawConfig.database,
username: rawConfig.username,
password: rawConfig.password,
select_only: rawConfig.select_only !== 'false'
};
}A new database is added by extending the abstract DatabaseAdapter, not by
implementing DatabaseConnection — that type is the driver's connection handle,
not the adapter contract. The subclass must supply every abstract member:
import { DatabaseAdapter } from '../../src/database/adapters/base.js';
import type { DatabaseConnection, QueryResult, DatabaseSchema } from '../../src/types/index.js';
class CustomAdapter extends DatabaseAdapter {
async connect(): Promise<DatabaseConnection> { /* ... */ }
async executeQuery(connection: DatabaseConnection, query: string, params?: unknown[]): Promise<QueryResult> { /* ... */ }
async disconnect(connection: DatabaseConnection): Promise<void> { /* ... */ }
async captureSchema(connection: DatabaseConnection): Promise<DatabaseSchema> { /* ... */ }
isConnected(connection: DatabaseConnection): boolean { /* ... */ }
async beginTransaction(connection: DatabaseConnection): Promise<void> { /* ... */ }
async commitTransaction(connection: DatabaseConnection): Promise<void> { /* ... */ }
async rollbackTransaction(connection: DatabaseConnection): Promise<void> { /* ... */ }
buildExplainQuery(query: string): string { /* ... */ }
protected extractRawRows(result: unknown): unknown[] { /* ... */ }
protected extractFieldNames(result: unknown): string[] { /* ... */ }
}examples/custom-adapters/adapter-template.ts is a complete version of the
above with each method commented, and is a better starting point than this
outline. Register the finished class in
src/database/adapters/AdapterFactory.ts.
Optionally override getPerformanceRecommendations(explainResult, query) to
turn the output of your buildExplainQuery into advice; the base implementation
returns nothing.
import {
SQLMCPError,
SecurityViolationError,
ConnectionError,
} from '../../src/utils/error-handler.js';
import { isSecurityViolationError } from '../../src/types/index.js';
async function handleDatabaseOperation() {
try {
// Database operation
await server.executeQuery('SELECT * FROM users');
} catch (error) {
if (isSecurityViolationError(error)) {
console.log('Security violation:', error.message);
console.log('Blocked operation:', error.details?.blockedOperation);
} else if (error instanceof ConnectionError) {
console.log('Connection error:', error.message);
console.log('Database:', error.details?.database);
} else if (error instanceof SQLMCPError) {
console.log('Argos Error:', error.code, error.message);
} else {
console.log('Unknown error:', error);
}
}
}This comprehensive TypeScript API reference provides developers with all the types, interfaces, and classes needed to work with or extend the Argos effectively.