MySQL MCP Server (Node.js)

이 저장소는 MySQL 데이터베이스에 연결할 수 있는 Smithery AI MCP 서버를 포함하고 있습니다. Node.js로 구현되어 있어 JSON 처리와 비동기 작업에 효율적입니다.

기능

• MySQL 데이터베이스 연결 및 쿼리 실행
• HTTP 및 WebSocket 프로토콜 모두 지원
• JSON-RPC 2.0 기반 통신 (WebSocket)
• RESTful API 제공 (HTTP)
• 환경 변수 기반 설정
• Docker 및 Smithery AI와 호환

로컬 개발 및 테스트

필수 요구 사항

• Node.js 18 이상
• MySQL 서버 (로컬 또는 원격)

설치 방법

1. 저장소 복제:

   git clone <repository-url>
   cd MCP_Server
   

2. 의존성 설치:

   npm install
   

3. 환경 변수 설정 (선택 사항):

   # Linux/macOS
   export MYSQL_HOST=localhost
   export MYSQL_PORT=3306
   export MYSQL_USER=your_username
   export MYSQL_PASSWORD=your_password
   export MYSQL_DATABASE=your_database
   
   # Windows (CMD)
   set MYSQL_HOST=localhost
   set MYSQL_PORT=3306
   set MYSQL_USER=your_username
   set MYSQL_PASSWORD=your_password
   set MYSQL_DATABASE=your_database
   

서버 실행

# 기본 HTTP 서버로 실행
node index.js

# 또는 WebSocket 서버로 실행
SERVER_TYPE=websocket node index.js

Docker로 실행

# Docker 이미지 빌드
docker build -t mysql-mcp-server .

# Docker 컨테이너 실행
docker run -p 3003:3003 \
  -e MYSQL_HOST=host.docker.internal \
  -e MYSQL_PORT=3306 \
  -e MYSQL_USER=your_username \
  -e MYSQL_PASSWORD=your_password \
  mysql-mcp-server

MCP 도구

mysql_query

MySQL 데이터베이스에 SQL 쿼리를 실행합니다.

매개변수:

• query: 실행할 SQL 쿼리 (필수)
• db_config: 데이터베이스 연결 설정 (선택 사항)
  • host: 데이터베이스 호스트
  • port: 데이터베이스 포트
  • user: 데이터베이스 사용자
  • password: 데이터베이스 비밀번호
  • database: 데이터베이스 이름

API 참조

HTTP API

GET /status

서버의 상태 정보를 반환합니다.

응답 예제:

{
  "status": "running",
  "type": "mysql",
  "tools": ["mysql_query"]
}

POST /execute

SQL 쿼리를 실행합니다.

요청 본문:

{
  "tool": "mysql_query",
  "parameters": {
    "query": "SELECT * FROM users",
    "db_config": {
      "host": "localhost",
      "port": 3306,
      "user": "root",
      "password": "password",
      "database": "mydb"
    }
  }
}

응답 예제 (성공):

{
  "results": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com"
    },
    {
      "id": 2,
      "name": "Jane Smith",
      "email": "jane@example.com"
    }
  ]
}

응답 예제 (오류):

{
  "error": "Database error: Access denied for user 'root'"
}

WebSocket API (JSON-RPC 2.0)

WebSocket을 통해 JSON-RPC 2.0 프로토콜로 통신합니다.

initialize

서버를 초기화하고 상태 정보를 반환합니다.

요청:

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {},
  "id": 1
}

응답:

{
  "jsonrpc": "2.0",
  "result": {
    "name": "MySQL MCP Server",
    "version": "1.0.0",
    "status": "initialized",
    "mysql_connection": "success",
    "config": {
      "mysql_host": "localhost",
      "mysql_port": 3306
    }
  },
  "id": 1
}

tools/list

사용 가능한 도구 목록을 반환합니다.

요청:

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "params": {},
  "id": 2
}

응답:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "name": "mysql_query",
      "description": "Execute a SQL query on MySQL database",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "SQL query to execute"
          },
          "db_config": {
            "type": "object",
            "description": "Optional database configuration",
            "properties": {
              "host": { "type": "string", "description": "Database host" },
              "port": { "type": "integer", "description": "Database port" },
              "user": { "type": "string", "description": "Database user" },
              "password": { "type": "string", "description": "Database password" },
              "database": { "type": "string", "description": "Database name" }
            }
          }
        },
        "required": ["query"]
      }
    }
  ],
  "id": 2
}

tools/call

도구를 호출하여 작업을 수행합니다.

요청:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "tool": "mysql_query",
    "params": {
      "query": "SELECT * FROM users"
    }
  },
  "id": 3
}

응답:

{
  "jsonrpc": "2.0",
  "result": {
    "results": [
      {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com"
      }
    ]
  },
  "id": 3
}

Smithery AI에 배포

이 서버는 Smithery AI에 배포할 수 있도록 설계되었습니다. 배포 과정은 다음과 같습니다:

1. Smithery 계정 생성: https://smithery.ai 에서 계정을 생성합니다.

2. 저장소 연결: GitHub 또는 다른 지원되는 저장소 서비스에 이 코드를 푸시하고, Smithery 대시보드에서 해당 저장소를 연결합니다.

3. 서버 배포: Smithery 대시보드에서 배포 과정을 따릅니다. Smithery는 Dockerfile과 smithery.yaml 파일을 사용하여 서버를 자동으로 구성하고 배포합니다.

4. 설정 구성: 배포 후, Smithery 대시보드에서 MySQL 연결 설정을 구성합니다.

구성 파일

smithery.yaml

version: 1
startCommand:
  type: stdio
  configSchema:
    # JSON Schema defining the configuration options for the MCP.
    type: object
    required:
      - mysqlHost
      - mysqlUser
      - mysqlPassword
      - mysqlDatabase
    properties:
      mysqlHost:
        type: string
        description: Hostname for the MySQL server
        default: localhost
      mysqlPort:
        type: integer
        description: Port for the MySQL server
        default: 3306
      mysqlUser:
        type: string
        description: MySQL user name
      mysqlPassword:
        type: string
        description: MySQL user's password
        format: password
      mysqlDatabase:
        type: string
        description: MySQL database name
      serverType:
        type: string
        description: Server type to run (websocket or http)
        enum: [websocket, http]
        default: http
  commandFunction: |-
    (config) => ({
      command: 'node',
      args: ['index.js'],
      env: {
        MYSQL_HOST: config.mysqlHost,
        MYSQL_PORT: String(config.mysqlPort || 3306),
        MYSQL_USER: config.mysqlUser,
        MYSQL_PASSWORD: config.mysqlPassword,
        MYSQL_DATABASE: config.mysqlDatabase,
        SERVER_TYPE: config.serverType || "http"
      }
    })
  exampleConfig:
    mysqlHost: localhost
    mysqlUser: example_user
    mysqlPassword: example_password
    mysqlDatabase: example_db

License

This project is licensed under the MIT License.