ablestack-mcp-server
ABLESTACK MOLD API를 MCP(Model Context Protocol)로 노출하는 서버입니다.
mold_* 네임스페이스의 MCP 툴을 통해 MOLD API를 직접 호출·탐색·디버그할 수 있습니다.
특징
- 연결정보 툴:
mold_getConfig,mold_setConfig(endpoint/apiKey/secret/algo 저장·조회) - 범용 호출:
mold_call→ 임의의 API 호출 - 서명 디버그:
mold_signDebug→ 정규화 문자열/서명/최종 URL 확인 - 자동 등록:
mold_autoRegisterApis,mold_listApisMeta
listApis메타를 읽어 모든 API를mold_툴로 동적 등록 - 비동기 폴링: isAsync API에
_wait,_timeoutMs,_intervalMs옵션 지원 - 브래킷 표기 변환: 중첩 params(JSON) →
details[0].cpuNumber=8등으로 자동 전개 - 서명 알고리즘 토글: HMAC-SHA1/SHA256 (서버/클라 동일해야 함)
요구 사항
- Node.js v18+
- 네트워크에서 MOLD API endpoint에 접근 가능
설치 & 실행```bash
의존성 설치
npm i
실행 (stdio)
node server.js
### Claude Desktop(또는 MCP 클라이언트) 연동 예시
`config.json` (클라이언트 설정) 예시:```json
{
"mcpServers": {
"mcp-mold-server": {
"command": "node",
"args": ["server.js"],
"env": {
"MOLD_ENDPOINT": "http://10.10.32.10:8080/client/api",
"MOLD_API_KEY": "<YOUR_API_KEY>",
"MOLD_SECRET_KEY": "<YOUR_SECRET_KEY>",
"MOLD_SIG_ALGO": "sha256", // 또는 "sha1"
"MOLD_AUTOREGISTER": "all" // (선택) 시작 시 전체 API 자동 등록
}
}
}
}
> 실행 후 MCP Inspector/Claude 등에서 툴이 표시됩니다.
툴 목록(핵심)
툴 이름 · 설명 · 입력 예시
mold_getConfig · 현재 endpoint/apiKey(마스킹)/algo/구성파일 경로 조회 · {}
mold_setConfig · 연결정보 설정 및 저장(persist=true면 디스크 저장) · {"endpoint":"http://HOST:8080/client/api","apiKey":"...","secret":"...","algo":"sha256","persist":true}
mold_signDebug · 서명 디버그(정규화 문자열·서명·최종 URL 생성) · {"command":"listVirtualMachines","params":{"listall":true}}
mold_call · 임의 API 호출(command + params) · {"command":"listZones"}
mold_listApisMeta · listApis 메타 조회(name/isasync/params) · {} 또는 {"name":"deployVirtualMachine"}
mold_autoRegisterApis · 모든 API를 MCP 툴로 동적 등록 · {"include":"^list · ^get","exclude":"Deprecated","limit":200}
mold_ · 자동 등록된 개별 API 툴(예: mold_deployVirtualMachine) · API별 파라미터(아래 표 참고)
> 자동 등록된 비동기 API(isasync=true)는 _wait, _timeoutMs, _intervalMs 옵션을 추가로 받습니다.
사용 예시
1) 연결정보 설정/확인```json
// 설정
{"endpoint":"http://10.10.32.10:8080/client/api","apiKey":"...","secret":"...","algo":"sha256","persist":true}
// 조회
{}
### 2) 기본 조회```json
// 존 목록
{"command":"listZones"}
// VM 목록
{"command":"listVirtualMachines","params":{"listall":true}}
3) 배포(비동기) — mold_call
입력(JSON):```json
{
"command": "deployVirtualMachine",
"params": {
"name": "MySQL-Server2",
"zoneid": "dbbaf9e7-865a-4c89-8a26-338c66ec2b81",
"details": { "memory": "16384", "cpuNumber": "8" },
"networkids": "91a24cde-38e4-494a-ae48-778d683ae735",
"templateid": "ca990e93-f2c0-4367-9f88-5bbc571e9fac",
"displayname": "MySQL-Server",
"serviceofferingid": "362c96c7-2b9c-4414-b9ca-9897da845080",
"boottype": "UEFI"
}
}
내부 전개(브래킷 표기; 서명 전에 적용):```
zoneid=...&serviceofferingid=...&details[0].cpuNumber=8&details[0].memory=16384&
networkids=...&name=MySQL-Server2&templateid=...&displayname=MySQL-Server&boottype=UEFI&
command=deployVirtualMachine
4) 자동 등록된 툴로 바로 호출```json
// 예: mold_deployVirtualMachine
{
"serviceofferingid": "362c96c7-2b9c-4414-b9ca-9897da845080",
"zoneid": "dbbaf9e7-865a-4c89-8a26-338c66ec2b81",
"templateid": "ca990e93-f2c0-4367-9f88-5bbc571e9fac",
"name": "MySQL-Server2",
"details": { "cpuNumber": "8", "memory": "16384" },
"_wait": true // 완료까지 폴링
}
```
파라미터 전개 규칙(브래킷 표기)
| 입력 타입 | 예시 입력 | 전송 형태 |
|---|---|---|
| 원시값 | "name":"vm01" |
name=vm01 |
| 원시 배열 | "securitygroupids":["id1","id2"] |
securitygroupids=id1,id2 (CSV) |
| 객체(톱레벨) | "details":{"cpuNumber":"8","memory":"16384"} |
details[0].cpuNumber=8, details[0].memory=16384 |
| 배열-객체 | "datadisks":[{"size":"50","diskofferingid":"..."},{"size":"100"}] |
datadisks[0].size=50, datadisks[0].diskofferingid=..., datadisks[1].size=100 |
| 이미 표기된 키 | "details[0].cpuNumber":"8" |
그대로 사용 |
> 복잡한 중첩 객체도 자동으로 전개됩니다. 이미 details[0].x와 같이 브래킷/닷 표기로 준 키는 수정하지 않습니다.
환경변수
| 이름 | 의미 | 기본 |
|---|---|---|
MOLD_ENDPOINT |
http(s)://HOST:PORT/client/api |
(없음) |
MOLD_API_KEY |
API 키 | (없음) |
MOLD_SECRET_KEY |
시크릿 키 | (없음) |
MOLD_SIG_ALGO |
sha1 또는 sha256 |
sha256 |
MOLD_AUTOREGISTER |
"all"이면 시작 시 전체 자동 등록 |
(비활성) |
> 실행 중에는 mold_setConfig로 변경·저장 가능. 저장 파일: ~/.config/mcp-mold/config.json (파일 권한 0600, 디렉터리 0700)
문제 해결(401 서명 오류 체크리스트)
| 증상 | 점검 |
|---|---|
User signature [...] is not equaled to computed signature [...] |
서버/클라 해시 알고리즘 일치(SHA1 vs SHA256), 키·시크릿 공백/개행 제거, 정규화 문자열(소문자·키정렬·값 URL 인코딩·공백 %20) 확인 |
| 401 계속 | CIDR 제한(api.allowed.source.cidr.list) 또는 권한 문제 |
| 일부 API만 실패 | 파라미터 누락/오타, 권한 부족 |
> mold_signDebug로 normalized/URL을 비교하면 원인을 빨리 찾을 수 있습니다.
보안
- API/Secret 키는 민감정보입니다. 노출 시 즉시 재발급(회전) 하세요.
- stdio 모드에선 stdout은 프로토콜 전용, 로그는 stderr만 사용해야 합니다.
라이선스
- LICENSE 파일을 확인하세요(MIT).
변경 이력(요약)
- 연결정보 툴 추가(get/set + 디스크 저장)
mold_*네임스페이스로 툴 이름 정규식 대응listApis기반 자동 도구 등록- 비동기 API 폴링 옵션 지원
- 브래킷 표기 변환기로 중첩 파라미터 처리
- SHA1/SHA256 서명 알고리즘 토글
