Skip to content

djsmithdev/dynapi-mcp

BranchesTags

Repository files navigation

🤖 DynAPI MCP Server

An intelligent Model Context Protocol (MCP) server that provides database analysis and query assistance for DynAPI.

📋 Overview

DynAPI MCP Server is a powerful tool that helps you:

  • Discover Database Schema: Automatically explore table relationships and structures
  • Suggest Optimal JOINs: Intelligently recommend JOIN operations between tables
  • Natural Language Queries: Convert plain English to working DynAPI queries
  • Performance Analysis: Analyze and optimize query performance
  • Generate Examples: Create example queries for any table or scenario

🚀 Quick Start

1. Install Dependencies

npm install

2. Configure Environment

Copy the example environment file and configure your settings:

cp .env.example .env
# Edit .env with your database and DynAPI settings

3. Build the Project

npm run build

4. Run the MCP Server

npm start

Or for development:

npm run dev

🔧 Configuration

Environment Variables

Create a .env file with the following variables:

# Database Connection (same as DynAPI)
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=your_username
DB_PASSWORD=your_password
DB_DATABASE=your_database
DB_SSL=false

# DynAPI Connection
DYNAPI_URL=http://localhost:4000
DYNAPI_API_KEY=your_api_key

# MCP Server Configuration
MCP_SERVER_NAME=dynapi-mcp
MCP_SERVER_VERSION=1.0.0
CACHE_TTL=3600
LOG_LEVEL=info

🛠️ MCP Tools

The server provides 5 powerful tools:

1. suggest_joins

Suggest optimal JOIN operations between database tables.

{
  "fromTable": "mapSolarSystems",
  "targetTables": ["mapRegions"],
  "maxDepth": 2
}

2. build_query

Convert natural language intent into DynAPI query syntax.

{
  "intent": "find all trading hubs in high-security space",
  "includeExamples": true
}

3. discover_schema

Explore database schema and relationships.

{
  "tableName": "mapSolarSystems",
  "includeRelationships": true
}

4. analyze_performance

Analyze query performance and suggest optimizations.

{
      "query": "http://localhost:4000/api/query/mapSolarSystems/*?security_gte=0.5",
  "includeSuggestions": true
}

5. generate_examples

Generate example queries for tables/scenarios.

{
  "tableName": "mapSolarSystems",
  "scenario": "trading hubs",
  "includeAdvanced": false
}

🎯 Integration

With Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "dynapi-intelligence": {
      "command": "node",
      "args": ["/path/to/dynapi-mcp/dist/server.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_DATABASE": "your_database",
        "DYNAPI_URL": "http://localhost:4000",
        "DYNAPI_API_KEY": "your-api-key"
      }
    }
  }
}

With Cursor IDE

Cursor IDE supports MCP servers through its built-in configuration system. Here's how to integrate the DynAPI MCP server:

Method 1: Cursor Settings (Recommended)

  1. Open Cursor Settings

    • Press Ctrl/Cmd + , to open settings
    • Search for "MCP" or navigate to Extensions → MCP

  2. Add MCP Server Configuration

    • Click "Add MCP Server" or edit the settings JSON directly
    • Copy the configuration from cursor-mcp-config.json or add the following configuration:
{
  "mcp.servers": {
    "dynapi-intelligence": {
      "command": "node",
      "args": ["/absolute/path/to/dynapi-mcp/dist/server.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_DATABASE": "your_database",
        "DYNAPI_URL": "http://localhost:4000",
        "DYNAPI_API_KEY": "your-api-key",
        "LOG_LEVEL": "info"
      },
      "timeout": 30000,
      "initializationOptions": {
        "capabilities": {
          "tools": true,
          "resources": true,
          "prompts": true
        }
      }
    }
  }
}

Method 2: Workspace Configuration

For project-specific setup, create a .cursor/mcp.json file in your workspace root:

{
  "servers": {
    "dynapi-intelligence": {
      "command": "node",
      "args": ["./dist/server.js"],
      "cwd": "/path/to/dynapi-mcp",
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_USERNAME": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_DATABASE": "your_database",
        "DYNAPI_URL": "http://localhost:4000",
        "DYNAPI_API_KEY": "your-api-key"
      }
    }
  }
}

Method 3: Environment File Integration (Alternative to Method 2)

If you prefer to keep sensitive credentials separate from configuration files, you can use an environment file approach:

  1. Create a .env.cursor file in your project root with your configurations:
# Database Configuration
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=your_username
DB_PASSWORD=your_password
DB_DATABASE=your_database
DB_SSL=false

# DynAPI Configuration
DYNAPI_URL=http://localhost:4000
DYNAPI_API_KEY=your_api_key

# MCP Server Configuration
MCP_SERVER_NAME=dynapi-mcp
MCP_SERVER_VERSION=1.0.0
CACHE_TTL=3600
LOG_LEVEL=info
  1. Create a .cursor/mcp.json file that references the environment file:
{
  "servers": {
    "dynapi-intelligence": {
      "command": "node",
      "args": ["./dist/server.js"],
      "cwd": "/path/to/dynapi-mcp",
      "envFile": ".env.cursor"
    }
  }
}

Note: This approach separates credentials from configuration, making it easier to share configuration files without exposing sensitive information.

Which Method Should You Choose?

  • Method 1 (Global Settings): Best for personal use when you want the MCP server available across all projects
  • Method 2 (Workspace Config): Best when credentials can be included in the config file or when working on a single project
  • Method 3 (Environment File): Best for teams/sharing when you need to keep credentials separate from configuration files

You only need to use one of these methods - they're alternatives, not meant to be used together.

Using the MCP Server in Cursor

Once configured, you can use the DynAPI MCP server directly in Cursor:

  1. Chat Integration: The MCP tools will be available in Cursor's chat interface
  2. Code Context: Use @dynapi-intelligence to reference the MCP server in conversations
  3. Direct Tool Access: Access tools like suggest_joins, build_query, etc. through chat commands

Example Usage in Cursor Chat:

User: @dynapi-intelligence suggest optimal joins for the mapSolarSystems table

Cursor: I'll analyze the mapSolarSystems table structure and suggest optimal JOIN operations.

[Uses suggest_joins tool]

Result: Here are the recommended JOINs for mapSolarSystems table:
- mapSolarSystems.regionID → mapRegions.regionID (Region information)
- mapSolarSystems.constellationID → mapConstellations.constellationID (Constellation data)
- mapSolarSystems.solarSystemID → mapSystemBodies.solarSystemID (System bodies)

Troubleshooting Cursor Integration

  1. Server Not Starting

    • Verify the absolute path to dist/server.js
    • Check that all dependencies are installed (npm install)
    • Ensure the server builds successfully (npm run build)

  2. Environment Variables Not Loading

    • Use absolute paths for environment files
    • Verify .env file syntax and permissions
    • Check Cursor logs for configuration errors

  3. Tools Not Available

    • Restart Cursor after configuration changes
    • Check the MCP server logs for initialization errors
    • Verify database and DynAPI connections are working

  4. Enable Debug Logging Set LOG_LEVEL=debug in your environment configuration to get detailed logs.

Quick Setup Files

This repository includes several template files to help you get started quickly:

  • cursor-mcp-config.json - Ready-to-use Cursor MCP server configuration
  • .env.example - Environment variables template
  • Copy and modify these files with your actual database and API credentials

Example AI Conversation

User: "I want to find all trading hubs in high-security space"

AI: I'll help you build that query using the DynAPI MCP server.

[Uses build_query tool]

Result: 
{
  "dynapiQuery": "http://localhost:4000/api/query/mapSolarSystems/solarSystemName,security?hub_eq=true&security_gte=0.5&join=regionID:mapRegions:regionID:regionName&orderBy=regionName",
  "explanation": "This query finds solar systems marked as hubs with security >= 0.5, including region names for context"
}

AI: Here's the perfect DynAPI query for finding trading hubs in high-security space:

```bash
curl -H "X-API-Key: your-key" \
  "http://localhost:4000/api/query/mapSolarSystems/solarSystemName,security?hub_eq=true&security_gte=0.5&join=regionID:mapRegions:regionID:regionName&orderBy=regionName"


## 🏗️ Architecture

dynapi-mcp/ ├── src/ │ ├── server.ts # Main MCP server entry point │ ├── config/ # Configuration modules │ ├── connectors/ # Database and API connectors │ ├── analyzers/ # Intelligence and analysis engines │ ├── tools/ # MCP tool implementations │ ├── types/ # TypeScript type definitions │ └── utils/ # Utility functions ├── dist/ # Compiled JavaScript output └── docs/ # Additional documentation


## 📚 Scripts

- `npm run build` - Compile TypeScript to JavaScript
- `npm start` - Run the compiled MCP server
- `npm run dev` - Run in development mode with hot reload
- `npm test` - Run test suite
- `npm run lint` - Run ESLint
- `npm run mcp:inspect` - Inspect MCP server with debugging tools

## 🐛 Troubleshooting

### Common Issues

1. **Database Connection Errors**
   - Verify your database credentials in `.env`
   - Ensure PostgreSQL is running and accessible
   - Check firewall settings

2. **DynAPI Connection Issues**
   - Verify `DYNAPI_URL` is correct
   - Check if DynAPI server is running
   - Validate your API key

3. **MCP Integration Problems**
   - Ensure the compiled server exists in `dist/server.js`
   - Check file paths in your MCP configuration
   - Verify environment variables are set correctly

### Debug Mode

Enable debug logging:

```bash
LOG_LEVEL=debug npm run dev

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature-name
  3. Make your changes and add tests
  4. Run the linter: npm run lint
  5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Related Projects

  • DynAPI - The core dynamic API server
  • WarView - EVE Online strategic mapping application

🌟 Features Coming Soon

  • Advanced query optimization recommendations
  • Machine learning-based relationship detection
  • Query result caching strategies
  • Multi-database support
  • GraphQL query generation
  • Automated documentation generation

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages