aspro-mcp

Model Context Protocol 서버로, Aspro.Cloud REST API를 LLM 클라이언트(Claude Desktop, Claude Code 등)에 노출합니다. 이 서버는 번들된 OpenAPI 사양을 포함하고 있어, 모델이 스스로 모듈, 엔티티 및 메서드를 검색하고 안전하게 호출할 수 있습니다.

기능

• 자체 설명(Self-describing). 모델은 aspro_list_modules → aspro_list_entities → aspro_list_methods → aspro_describe를 통해 API를 탐색한 후 aspro_call을 수행하므로 엔드포인트를 외울 필요가 없습니다.

• 부분 문자열 검색. 모듈 / 엔티티 / 메서드 / 경로 / 설명 / 태그 전반에 걸친 검색을 지원합니다.

• 기본 Form-urlencoded POST. Aspro에서 예상하는 콘텐츠 유형을 따르며, 배열 및 중첩 객체 처리를 지원합니다.

• 경로 매개변수 대체. /get/{id}, /update/{id}, /delete/{id} 등과 같은 경로에 대한 매개변수 대체를 지원합니다.

• 테넌트별 설정. ASPRO_COMPANY(서브도메인) 또는 전체 ASPRO_BASE_URL을 통해 설정 가능합니다.

설치

git clone https://github.com/bssth/aspro-mcp.git
cd aspro-mcp
npm install
npm run build

Node.js ≥ 18 버전이 필요합니다.

설정

예제 env 파일을 복사하여 내용을 채우세요:

cp .env.example .env

ASPRO_COMPANY=your_company        # the {company} part of https://{company}.aspro.cloud
ASPRO_API_KEY=your_api_key_here   # passed as ?api_key=... on every request
# ASPRO_BASE_URL=...              # optional; overrides the URL built from ASPRO_COMPANY
# ASPRO_TIMEOUT_MS=30000          # optional; default 30s

Aspro.Cloud 계정의 설정 → 통합 → API에서 API 키를 발급받으세요.

클라이언트 연결

Claude Desktop / Claude Code

MCP 설정에 서버를 추가하세요:

{
  "mcpServers": {
    "aspro": {
      "command": "node",
      "args": ["/absolute/path/to/aspro-mcp/dist/index.js"]
    }
  }
}

서버는 클라이언트가 실행되는 작업 디렉터리와 관계없이 프로젝트 루트에서 .env 파일을 읽습니다.

기타 MCP 클라이언트

stdio를 통해 MCP를 지원하는 모든 클라이언트는 node dist/index.js (또는 npm start)를 실행할 수 있습니다.

노출된 도구

권장되는 흐름은 search/list_* → describe → call입니다.

개발

npm run dev      # tsc --watch
npm run build    # tsc
npm run smoke    # offline: exercises the spec indexer and URL builder

스모크 테스트는 네트워크에 연결되지 않으며, 번들된 OpenAPI 사양이 구문 분석되는지, 작업을 설명할 수 있는지, URL 빌더가 올바른 형식의 URL을 생성하는지 확인합니다.

프로젝트 구조

src/
  index.ts    MCP server (tool registration + entry point)
  config.ts   .env loading and validation
  client.ts   HTTP client (URL building, form-urlencoded POSTs, timeouts)
  spec.ts    OpenAPI indexer (modules / entities / methods / search / describe)
  smoke.ts    offline smoke test
spec/
  openapi.json  bundled Aspro.Cloud OpenAPI spec

보안 참고 사항

• API 키는 환경 변수에서 읽어오며 모든 요청에 ?api_key=...로 추가됩니다. .env 파일을 절대 커밋하지 마십시오.

• 서버에는 허용 목록(allowlist)이 없습니다. 설정이 완료되면 사양에 설명된 모든 엔드포인트(예: /delete/{id}와 같은 파괴적인 작업 포함)를 호출할 수 있습니다. 필요한 최소 권한만 가진 전용 API 키를 사용하십시오.

• 도구 출력을 신뢰할 수 없는 것으로 처리하십시오. Aspro 엔티티(사용자 정의 필드 값, 설명 등)에는 사용자가 제공한 콘텐츠가 포함될 수 있습니다.

기여

이슈 및 PR을 환영합니다. 제출하기 전에 npm run build && npm run smoke를 실행해 주십시오.

라이선스

MIT — LICENSE를 참조하십시오.

aspro-mcp는 비공식 타사 커넥터이며 Aspro.Cloud와 제휴되어 있지 않습니다.