#!/usr/bin/env node
/**
* postgres-mcp - CLI Entry Point
*
* Command-line interface for the PostgreSQL MCP server.
* Supports stdio, HTTP, and SSE transports with OAuth 2.0 authentication.
*/
import { Command } from 'commander';
import { PostgresAdapter } from './adapters/postgresql/index.js';
import { PostgresMcpServer } from './server/McpServer.js';
import { parseToolFilter, getFilterSummary } from './filtering/ToolFilter.js';
import { logger } from './utils/logger.js';
import { HttpTransport, type HttpTransportConfig } from './transports/http.js';
import {
OAuthResourceServer,
TokenValidator,
AuthorizationServerDiscovery,
ALL_SCOPES
} from './auth/index.js';
import type { DatabaseConfig, OAuthConfig, TransportType } from './types/index.js';
const VERSION = '0.1.0';
interface CliOptions {
postgres?: string;
host?: string;
pgPort?: number;
user?: string;
password?: string;
database?: string;
ssl?: boolean;
poolMax?: number;
toolFilter?: string;
logLevel?: 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
transport?: TransportType;
port?: number;
oauthEnabled?: boolean;
oauthIssuer?: string;
oauthAudience?: string;
oauthJwksUri?: string;
oauthClockTolerance?: number;
}
interface ListToolsOptions {
filter?: string;
group?: string;
}
const program = new Command();
program
.name('postgres-mcp')
.description('PostgreSQL MCP Server - Full-featured database tools for AI with OAuth 2.0')
.version(VERSION);
program
// Connection options
.option('--postgres <url>', 'PostgreSQL connection string (postgres://user:pass@host:port/database)')
.option('--host <host>', 'PostgreSQL host (default: localhost)')
.option('--pg-port <port>', 'PostgreSQL port (default: 5432)', parseInt)
.option('--user <user>', 'PostgreSQL username')
.option('--password <password>', 'PostgreSQL password')
.option('--database <database>', 'PostgreSQL database name')
.option('--ssl', 'Enable SSL connection')
.option('--pool-max <size>', 'Maximum pool connections (default: 10)', parseInt)
// Server options
.option('--transport, -t <type>', 'Transport type: stdio, http, sse (default: stdio)')
.option('--port, -p <port>', 'HTTP port for http/sse transports (default: 3000)', parseInt)
.option('--tool-filter <filter>', 'Tool filter string (e.g., "-vector,-postgis")')
.option('--log-level <level>', 'Log level: debug, info, notice, warning, error, critical, alert, emergency (default: info)')
// OAuth options
.option('--oauth-enabled, -o', 'Enable OAuth 2.0 authentication')
.option('--oauth-issuer <url>', 'Authorization server URL (issuer)')
.option('--oauth-audience <aud>', 'Expected token audience')
.option('--oauth-jwks-uri <url>', 'JWKS URI (auto-discovered from issuer if not set)')
.option('--oauth-clock-tolerance <seconds>', 'Clock tolerance in seconds (default: 60)', parseInt)
.action(async (options: CliOptions) => {
// Set log level
const logLevel = options.logLevel ?? (process.env['LOG_LEVEL'] as typeof options.logLevel);
if (logLevel) {
logger.setLevel(logLevel);
}
// Build database config
const dbConfig = buildDatabaseConfig(options);
// Build OAuth config
const oauthConfig = await buildOAuthConfig(options);
// Create adapter and connect
const adapter = new PostgresAdapter();
try {
await adapter.connect(dbConfig);
// Get tool filter from option or environment
const toolFilter = options.toolFilter ??
process.env['POSTGRES_TOOL_FILTER'] ??
process.env['MCP_TOOL_FILTER'];
if (toolFilter) {
const filterConfig = parseToolFilter(toolFilter);
logger.info(getFilterSummary(filterConfig));
}
// Log OAuth status
if (oauthConfig?.enabled) {
logger.info('OAuth 2.0 authentication enabled', { issuer: oauthConfig.issuer });
}
// Determine transport type
const transport = (options.transport ?? process.env['MCP_TRANSPORT'] ?? 'stdio') as TransportType;
if (transport === 'http' || transport === 'sse') {
// Start with HTTP transport
await startHttpServer(adapter, toolFilter, oauthConfig, options);
} else {
// Start with stdio transport (default)
await startStdioServer(adapter, toolFilter);
}
} catch (error) {
logger.error('Failed to start server', {
error: error instanceof Error ? error.message : String(error)
});
await adapter.disconnect();
process.exit(1);
}
});
/**
* Build database configuration from CLI options and environment
*/
function buildDatabaseConfig(options: CliOptions): DatabaseConfig {
const config: DatabaseConfig = {
type: 'postgresql'
};
// Parse connection string or individual options
if (options.postgres) {
const url = new URL(options.postgres);
config.host = url.hostname;
config.port = parseInt(url.port, 10) || 5432;
config.username = url.username;
config.password = url.password;
config.database = url.pathname.slice(1); // Remove leading /
if (url.searchParams.get('ssl') === 'true' || url.searchParams.get('sslmode') === 'require') {
config.options = { ssl: true };
}
} else {
config.host = options.host ?? process.env['PGHOST'] ?? process.env['POSTGRES_HOST'] ?? 'localhost';
config.port = options.pgPort ?? parseInt(process.env['PGPORT'] ?? process.env['POSTGRES_PORT'] ?? '5432', 10);
config.username = options.user ?? process.env['PGUSER'] ?? process.env['POSTGRES_USER'] ?? 'postgres';
config.password = options.password ?? process.env['PGPASSWORD'] ?? process.env['POSTGRES_PASSWORD'] ?? '';
config.database = options.database ?? process.env['PGDATABASE'] ?? process.env['POSTGRES_DATABASE'] ?? 'postgres';
if (options.ssl) {
config.options = { ssl: true };
}
}
// Pool configuration
if (options.poolMax !== undefined && options.poolMax > 0) {
config.pool = { max: options.poolMax };
}
return config;
}
/**
* Build OAuth configuration from CLI options and environment
*/
async function buildOAuthConfig(options: CliOptions): Promise<OAuthConfig | undefined> {
// Check if OAuth is enabled
const oauthEnabled = options.oauthEnabled ??
process.env['OAUTH_ENABLED'] === 'true';
if (!oauthEnabled) {
return undefined;
}
const issuer = options.oauthIssuer ?? process.env['OAUTH_ISSUER'];
const audience = options.oauthAudience ?? process.env['OAUTH_AUDIENCE'];
let jwksUri = options.oauthJwksUri ?? process.env['OAUTH_JWKS_URI'];
const clockTolerance = options.oauthClockTolerance ??
(process.env['OAUTH_CLOCK_TOLERANCE'] ? parseInt(process.env['OAUTH_CLOCK_TOLERANCE'], 10) : 60);
// Auto-discover JWKS URI if not provided
if (!jwksUri && issuer) {
try {
const discovery = new AuthorizationServerDiscovery({ authServerUrl: issuer });
jwksUri = await discovery.getJwksUri();
logger.debug('JWKS URI discovered from issuer', { jwksUri });
} catch (error) {
logger.warn('Failed to discover JWKS URI, OAuth may not work correctly', {
error: String(error)
});
}
}
// Build OAuth config (we already checked oauthEnabled at function start)
const oauthConfig: OAuthConfig = {
enabled: true,
clockTolerance
};
if (issuer) oauthConfig.authorizationServerUrl = issuer;
if (issuer) oauthConfig.issuer = issuer;
if (audience) oauthConfig.audience = audience;
if (jwksUri) oauthConfig.jwksUri = jwksUri;
return oauthConfig;
}
/**
* Start the server with stdio transport
*/
async function startStdioServer(adapter: PostgresAdapter, toolFilter?: string): Promise<void> {
const server = new PostgresMcpServer({
name: 'postgres-mcp',
version: VERSION,
adapter,
toolFilter
});
// Handle shutdown
const shutdown = (): void => {
logger.info('Shutting down...');
void server.stop().then(() => adapter.disconnect()).then(() => process.exit(0));
};
process.on('SIGINT', shutdown);
process.on('SIGTERM', shutdown);
await server.start();
}
/**
* Start the server with HTTP transport
*/
async function startHttpServer(
adapter: PostgresAdapter,
toolFilter: string | undefined,
oauthConfig: OAuthConfig | undefined,
options: CliOptions
): Promise<void> {
const port = options.port ?? parseInt(process.env['PORT'] ?? '3000', 10);
const host = process.env['HOST'] ?? 'localhost';
// Create OAuth components if enabled
let resourceServer: OAuthResourceServer | undefined;
let tokenValidator: TokenValidator | undefined;
if (oauthConfig?.enabled && oauthConfig.issuer && oauthConfig.jwksUri && oauthConfig.audience) {
resourceServer = new OAuthResourceServer({
resource: `http://${host}:${String(port)}`,
authorizationServers: [oauthConfig.issuer],
scopesSupported: [...ALL_SCOPES]
});
tokenValidator = new TokenValidator({
jwksUri: oauthConfig.jwksUri,
issuer: oauthConfig.issuer,
audience: oauthConfig.audience,
clockTolerance: oauthConfig.clockTolerance
});
}
// Create MCP server
const mcpServer = new PostgresMcpServer({
name: 'postgres-mcp',
version: VERSION,
adapter,
toolFilter
});
// Build HTTP transport config
const transportConfig: HttpTransportConfig = {
port,
host,
publicPaths: oauthConfig?.publicPaths ?? ['/health', '/.well-known/*']
};
if (resourceServer) transportConfig.resourceServer = resourceServer;
if (tokenValidator) transportConfig.tokenValidator = tokenValidator;
// Create HTTP transport with OAuth
const httpTransport = new HttpTransport(transportConfig, (transport) => {
// Connect MCP server to the transport when client connects
// eslint-disable-next-line @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-explicit-any
void mcpServer.getMcpServer().connect(transport as any);
});
// Handle shutdown
const shutdown = (): void => {
logger.info('Shutting down...');
void httpTransport.stop()
.then(() => mcpServer.stop())
.then(() => adapter.disconnect())
.then(() => process.exit(0));
};
process.on('SIGINT', shutdown);
process.on('SIGTERM', shutdown);
// Start HTTP server
await httpTransport.start();
logger.info(`PostgreSQL MCP Server started on http://${host}:${String(port)}`);
if (oauthConfig?.enabled) {
logger.info('OAuth 2.0 protected resource metadata available at /.well-known/oauth-protected-resource');
}
}
// List tools command
program
.command('list-tools')
.description('List all available tools')
.option('--filter <filter>', 'Apply tool filter')
.option('--group <group>', 'Filter by tool group')
// eslint-disable-next-line @typescript-eslint/require-await
.action(async (options: ListToolsOptions) => {
const adapter = new PostgresAdapter();
const tools = adapter.getToolDefinitions();
const filterConfig = parseToolFilter(options.filter);
let filteredTools = tools;
if (options.group) {
filteredTools = tools.filter(t => t.group === options.group);
}
filteredTools = filteredTools.filter(t => filterConfig.enabledTools.has(t.name));
// Use stderr for all output - stdout is reserved for MCP protocol
console.error(`\nPostgreSQL MCP Tools (${String(filteredTools.length)}/${String(tools.length)}):\n`);
// Group by category
const grouped = new Map<string, typeof tools>();
for (const tool of filteredTools) {
const groupTools = grouped.get(tool.group) ?? [];
groupTools.push(tool);
grouped.set(tool.group, groupTools);
}
for (const [group, groupTools] of grouped) {
console.error(`[${group}] (${String(groupTools.length)})`);
for (const tool of groupTools) {
const desc = tool.description.split('.')[0] ?? '';
console.error(` - ${tool.name}: ${desc}`);
}
console.error('');
}
});
// Print tool count
program
.command('info')
.description('Show server information')
// eslint-disable-next-line @typescript-eslint/require-await
.action(async () => {
const adapter = new PostgresAdapter();
const tools = adapter.getToolDefinitions();
const resources = adapter.getResourceDefinitions();
const prompts = adapter.getPromptDefinitions();
const groups = adapter.getSupportedToolGroups();
// Use stderr for all output - stdout is reserved for MCP protocol
console.error('\nPostgreSQL MCP Server');
console.error('=====================');
console.error(`Version: ${VERSION}`);
console.error(`Tools: ${String(tools.length)}`);
console.error(`Resources: ${String(resources.length)}`);
console.error(`Prompts: ${String(prompts.length)}`);
console.error(`Tool Groups: ${groups.join(', ')}`);
console.error('\nTransports: stdio (default), http, sse');
console.error('OAuth 2.0: Supported (RFC 9728/8414)');
console.error('\nCapabilities:');
const caps = adapter.getCapabilities();
for (const [cap, enabled] of Object.entries(caps)) {
console.error(` ${cap}: ${enabled ? '✓' : '✗'}`);
}
});
program.parse();
