real-mcp — Wooritech Real-* MCP Tools

real-mcp 는 Model Context Protocol(MCP) 기반의 RealGrid, RealReport, RealChart, RealMap 등 멀티-프로덕트 서버로 문서/리소스에 접근할 수 있게 해줍니다.

패키지: real-mcp | 버전: 1.0.0

주요 요약:

• 빠른 실행: npx real-mcp로 즉시 사용 가능
• CLI 및 stdio 기반 MCP 서버를 제공하여 LangChain 등 MCP 클라이언트와 연동

지원 Node 버전: node >= 18

설치 (간단)

• npx (권장 — 설치 불필요):

npx real-mcp

• 전역 설치:

npm install -g real-mcp

빠른 사용법 (npx)

• 기본 실행 (production 기본 설정 사용):

npx real-mcp

프로그램적 사용 (MCP 클라이언트 예시)

LangChain의 @langchain/mcp-adapters 같은 클라이언트에서 npx real-mcp를 stdio로 실행하도록 설정하면, 에이전트가 MCP를 통해 서버에서 제공하는 툴과 리소스에 접근할 수 있습니다.

예시 (간단한 구성):

// 예: @langchain/mcp-adapters 사용 시
import { MultiServerMCPClient } from '@langchain/mcp-adapters';

const client = new MultiServerMCPClient({
  mcpServers: {
    "real-mcp": {
      transport: 'stdio',
      command: 'npx',
      args: ['real-mcp'],
    },
  },
});

const tools = await client.getTools();
// 사용 후 종료
await client.close();

CLI/실행 옵션

• 이 패키지는 dist/index.js를 통해 CLI로 동작하며, 기본적으로 MCP stdio 서버를 시작합니다.
• HTTP 모드: node dist/index.js http (기본 포트 3100, PORT 환경변수로 변경 가능)

로그 (stderr)

MCP stdio 서버는 stdout을 JSON-RPC 전용으로 쓰므로, 모든 로그는 stderr로 출력합니다 (MCP Debugging).

| LOG_LEVEL | stderr 출력 | |-------------|-------------| | (미설정) | startup INFO + ERROR | | debug | 위 + tool/search/resource 추적 DEBUG |

개발 시 MCP Inspector로 tool/resource를 먼저 테스트하는 것을 권장합니다:

npx @modelcontextprotocol/inspector node dist/index.js

LOG_LEVEL=debug일 때 MCP 출력(Cursor MCP 로그 등)에 예시처럼 보입니다.

[real-mcp][DEBUG] tool=search_resources product=realgrid query="license"
[real-mcp][DEBUG] tool=search_resources 3 hit(s): #1 sim=0.891 uri=/realgrid/guides/...
[real-mcp][DEBUG] tool=get_resource resolved=/realgrid/guides/getting-started
[real-mcp][DEBUG] tool=get_resource ok=/realgrid/guides/getting-started chars=12450

Cursor MCP 설정 예시

{
  "mcpServers": {
    "real-mcp": {
      "command": "node",
      "args": ["/path/to/argus/dist/index.js"],
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

CLI에서 직접 실행

LOG_LEVEL=debug node dist/index.js
LOG_LEVEL=debug node dist/index.js http

stdio·HTTP 모드 모두 stderr + LOG_LEVEL을 사용합니다. Cursor MCP 설정 변경 후 서버를 재연결(또는 재시작)하세요.

Examples

• 저장소의 examples/ 디렉터리 참조:
  • examples/langchain-client.ts — @langchain/mcp-adapters 사용 예
  • examples/agent-example.ts — 에이전트 통합 예

실행 예시(빌드 후):

npm run build
npx tsx examples/langchain-client.ts

AI 에이전트용 안내 (MCP instructions)

서버 초기화(initialize) 시 instructions 필드로 에이전트에게 워크플로를 전달합니다.

• RealGrid / RealChart 관련 질문은 웹 검색보다 이 MCP를 우선 사용
• 키워드 질문: search_resources → document.pageContent로 충분하면 종료, 아니면 get_resource(uri) (검색 hit에 uri 포함)
• 목록 탐색: list_resources → get_resource(uri)
• API 타입: list_dts_files → get_package_file

Cursor 등 MCP 클라이언트가 instructions를 시스템 컨텍스트에 포함하면, 에이전트가 RealGrid 문서를 먼저 조회합니다.

문제 해결 팁

• npx real-mcp가 실패하면 로컬에서 먼저 npm run build 후 node dist/index.js로 실행해 보세요.
• Node 버전을 확인하세요: node -v (최소 v18 이상 권장)

라이선스

• Wooritech Inc.

배포 (Release)

• 사전 준비: npm에 로그인되어 있어야 합니다.

npm login

• 빌드:

npm run build

• npm에 배포:

npm publish