Omnibase MCP Server for AI Agents

Common errors

• Error: Database connection failed: <Driver not found or connection string invalid>

  cause The Omnibase MCP server could not establish a connection to the configured database, likely due to a missing driver, incorrect connection string, or inaccessible database server.
  fix Ensure the required database driver (e.g., `pg` for PostgreSQL, `mysql2` for MySQL) is installed as a dependency if not bundled. Verify the database server is running and accessible from the MCP server, and that the connection string in the configuration is correct.

• Error: Unknown command: <command>

  cause When running `omnibase-mcp` from the command line, an unrecognized argument or subcommand was provided. The CLI interface is subject to change.
  fix Run `omnibase-mcp --help` to see a list of available commands and their options for your installed version. Check the package's changelog for recent CLI changes.

• Error: Configuration validation failed: <details about missing/invalid field>

  cause The server failed to start because the provided configuration object (either from a file or programmatic) does not conform to the expected schema, possibly due to a missing required field or an invalid value type.
  fix Review the `McpConfig` type definition or the example configuration in the documentation. Ensure all required fields are present and correctly typed. This is particularly relevant given the rapid development pace and potential for config schema changes.

Warnings

• breaking As a 0.1.x package, `omnibase-mcp` is in an early development stage. APIs are highly unstable and breaking changes are frequent across minor and patch versions without explicit major version bumps. Always review changelogs between updates.
  Fix: Pin to exact patch versions (`~0.1.x` or `0.1.x`) or exact minor versions (`^0.1.x`) and thoroughly test updates. Monitor the GitHub repository for breaking changes and development progress.
• gotcha The package relies on a dynamic driver plugin architecture for database connectivity. This implies that specific database drivers (e.g., PostgreSQL, MySQL) might need to be separately installed or configured at runtime for the server to function with those databases.
  Fix: Consult the Omnibase documentation for instructions on installing and configuring specific database drivers required by your setup. Ensure all necessary runtime dependencies are met before starting the server.
• gotcha Frequent releases (multiple per month) indicate rapid development, but also potential instability or unannounced changes in behavior. Pay close attention to CLI command arguments and configuration file formats which may evolve quickly.
  Fix: Always refer to the latest documentation or `--help` output for CLI commands. Back up configurations before updating and test in a staging environment.
• gotcha Past releases indicate issues with the npm publish payload (e.g., README not included, or being blocked by WAFs). While fixed in specific versions, this highlights potential for inconsistent package content or build issues in future pre-1.0 releases.
  Fix: Verify package contents after `npm install` if unexpected behavior occurs, especially around documentation or assets. Report any inconsistencies to the maintainers.

Install

• npm install omnibase-mcp npm
• yarn add omnibase-mcp yarn
• pnpm add omnibase-mcp pnpm

Imports

• startMcp

  import { startMcp } from 'omnibase-mcp';

  Used to programmatically start the MCP server. This is a common entry point for embedded or test environments, rather than direct CLI usage.
• Server

  import { Server } from 'omnibase-mcp';

  The core Server class allows for advanced programmatic configuration and management of the MCP server instance.
• McpConfig

  import type { McpConfig } from 'omnibase-mcp';

  Represents the configuration interface for the MCP server, useful for TypeScript users to ensure type safety when defining server settings.

Quickstart

This quickstart demonstrates how to programmatically start the Omnibase MCP server with a basic SQLite database configuration, showing typical server setup and graceful shutdown handling.

import { startMcp } from 'omnibase-mcp';
import path from 'path';

async function main() {
  // Example configuration for the MCP server. Real applications would fetch this securely.
  const config = {
    // Ensure your database drivers are available at runtime or via plugins.
    databases: [
      {
        name: 'my_app_db',
        type: 'sqlite',
        connectionString: 'sqlite://' + path.join(process.cwd(), 'my_app.sqlite'),
      },
      // Add more database configurations here (e.g., PostgreSQL, MySQL)
    ],
    // The port on which the MCP server will listen.
    port: process.env.MCP_SERVER_PORT ? parseInt(process.env.MCP_SERVER_PORT) : 8000,
    // Enable or disable specific features, e.g., custom tools.
    enableCustomTools: true,
    logLevel: 'info'
  };

  try {
    console.log(`Starting Omnibase MCP server on port ${config.port}...`);
    // Start the MCP server programmatically
    const server = await startMcp(config);
    console.log('Omnibase MCP server started successfully.');

    // Keep the process alive, or set up graceful shutdown handlers
    process.on('SIGINT', async () => {
      console.log('Stopping Omnibase MCP server...');
      // Assuming server.close() exists for graceful shutdown
      // await server.close(); 
      console.log('Omnibase MCP server stopped.');
      process.exit(0);
    });
    process.on('SIGTERM', async () => {
      console.log('Stopping Omnibase MCP server...');
      // await server.close();
      console.log('Omnibase MCP server stopped.');
      process.exit(0);
    });

  } catch (error) {
    console.error('Failed to start Omnibase MCP server:', error);
    process.exit(1);
  }
}

main();