TypeScript로 MCP 서버 만들기: Hermes AI 에이전트에 PostgreSQL·Grafana를 연결하는 법

# hermes config.yaml — 가장 기본적인 구조
mcp_servers:
  서버이름:
    command: "실행할 명령어"
    args: ["인자들"]
    allowed_tools:
      - "허용할_도구_이름"

pnpm init
pnpm add @modelcontextprotocol/sdk pg zod
pnpm add -D typescript @types/pg tsx

// src/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { Pool } from "pg";
import { z } from "zod";
 
// 시작 시점에 환경 변수 검증 — undefined면 Pool 생성 전에 즉시 종료
const DB_URL = process.env.DB_URL;
if (!DB_URL) {
  console.error("오류: DB_URL 환경 변수가 설정되지 않았습니다.");
  process.exit(1);
}
 
const server = new McpServer({ name: "internal-db-mcp", version: "1.0.0" });
const pool = new Pool({ connectionString: DB_URL, max: 5 });
 
// 코드 레벨 참조용 화이트리스트
// 주의: 이 목록만으로는 DB 레벨 접근을 막지 못합니다.
//       실제 접근 제어는 읽기 전용 계정 + 뷰(view) 권한으로 처리해야 합니다.
const ALLOWED_TABLES = ["orders", "services", "error_logs", "metrics"];
 
function validateSql(sql: string): string | null {
  if (!/^\s*SELECT\b/i.test(sql)) return "SELECT 쿼리만 허용됩니다.";
  // 세미콜론 차단: "SELECT 1; DROP TABLE orders" 같은 다중 구문 인젝션 방어
  if (/;/.test(sql)) return "세미콜론은 허용되지 않습니다.";
  // 주석 차단: "--" 또는 "/*" 주석으로 필터를 우회하는 시도 방어
  if (/--|\/\*/.test(sql)) return "SQL 주석은 허용되지 않습니다.";
  return null;
}
 
server.tool(
  "query_metrics",
  "지표 데이터 조회 (읽기 전용)",
  {
    sql: z.string().describe("실행할 SELECT 쿼리"),
    limit: z.number().min(1).max(500).default(100),
  },
  async ({ sql, limit }) => {
    const validationError = validateSql(sql);
    if (validationError) {
      return {
        content: [{ type: "text", text: `오류: ${validationError}` }],
        isError: true,
      };
    }
 
    // 원본 쿼리에 LIMIT이 이미 있으면 중복 추가 시 문법 오류가 발생하므로 분기 처리
    const hasLimit = /\bLIMIT\b/i.test(sql);
    const finalSql = hasLimit ? sql : `${sql} LIMIT $1`;
    const params = hasLimit ? [] : [limit];
 
    try {
      const result = await pool.query(finalSql, params);
      return {
        content: [{ type: "text", text: JSON.stringify(result.rows, null, 2) }],
      };
    } catch (err) {
      return {
        content: [
          {
            type: "text",
            text: `쿼리 실행 오류: ${err instanceof Error ? err.message : "알 수 없는 오류"}`,
          },
        ],
        isError: true,
      };
    }
  }
);
 
server.tool(
  "list_tables",
  "조회 가능한 테이블 목록 반환",
  {},
  async () => ({
    content: [{ type: "text", text: ALLOWED_TABLES.join("\n") }],
  })
);
 
server.tool(
  "describe_table",
  "테이블 스키마 조회",
  {
    // z.enum()은 최소 하나 이상인 튜플 타입 [string, ...string[]]을 요구합니다.
    // TypeScript가 ALLOWED_TABLES를 일반 string[]으로 추론하기 때문에 이 캐스팅이 필요합니다.
    table_name: z.enum(ALLOWED_TABLES as [string, ...string[]]),
  },
  async ({ table_name }) => {
    try {
      const result = await pool.query(
        `SELECT column_name, data_type, is_nullable
         FROM information_schema.columns
         WHERE table_name = $1
         ORDER BY ordinal_position`,
        [table_name]
      );
      return {
        content: [{ type: "text", text: JSON.stringify(result.rows, null, 2) }],
      };
    } catch (err) {
      return {
        content: [
          {
            type: "text",
            text: `스키마 조회 오류: ${err instanceof Error ? err.message : "알 수 없는 오류"}`,
          },
        ],
        isError: true,
      };
    }
  }
);
 
const transport = new StdioServerTransport();
await server.connect(transport);

# hermes config.yaml
mcp_servers:
  internal_db:
    command: "pnpm"
    args: ["exec", "tsx", "/path/to/internal-db-mcp/src/server.ts"]
    env:
      DB_URL: "postgresql://readonly_user:pass@db.internal:5432/prod"
    allowed_tools:
      - "query_metrics"
      - "list_tables"
      - "describe_table"

# hermes config.yaml — 모니터링 서버 추가
mcp_servers:
  internal_db:
    command: "pnpm"
    args: ["exec", "tsx", "/path/to/internal-db-mcp/src/server.ts"]
    env:
      DB_URL: "postgresql://readonly_user:pass@db.internal:5432/prod"
    allowed_tools:
      - "query_metrics"
      - "list_tables"
      - "describe_table"
 
  grafana:
    command: "npx"
    args:
      - "@grafana/mcp-grafana"
      - "--grafana-url"
      - "http://grafana.internal:3000"
      - "--api-key"
      - "${GRAFANA_API_KEY}"
    # 주의: ${...} 환경 변수 인터폴레이션은 Hermes 설정 파서가 지원해야 작동합니다.
    # 미지원 시 env: 블록에 GRAFANA_API_KEY를 직접 지정하는 방식으로 대체해 주세요.
    allowed_tools:
      - "list_dashboards"
      - "get_dashboard"
      - "query_datasource"
      - "list_alerts"
 
  prometheus:
    command: "python"
    args: ["-m", "prometheus_mcp_server"]
    # 커뮤니티 패키지입니다. GitHub: github.com/pab1it0/prometheus-mcp-server
    env:
      PROMETHEUS_URL: "http://prometheus.internal:9090"

hermes mcp list
 
# 출력 예시
internal_db:
  - query_metrics: Execute SQL query on internal database
  - list_tables: List all available tables
  - describe_table: Show table schema
 
grafana:
  - list_dashboards: List all Grafana dashboards
  - get_dashboard: Get dashboard details
  - query_datasource: Execute query against a data source
  - list_alerts: List active alerts
 
prometheus:
  - query_range: Execute PromQL range query
  - query_instant: Execute instant PromQL query

"지난 1시간 동안 API 응답 시간이 500ms를 초과한 서비스 목록을 보여주고,
 해당 서비스들의 DB 쿼리 오류 현황도 함께 알려줘"