README.md

@promstack-1/mcp-server

PromStack의 공식 MCP(Model Context Protocol) 서버 구현체입니다.
**Official @modelcontextprotocol/sdk**를 사용하여 안정성과 호환성을 보장합니다.

이 서버를 통해 Claude Desktop, Cursor 등 MCP 호환 도구에서 PromStack의 프롬프트를 직접 불러오고 실행할 수 있습니다.

🚀 시작하기

1. 사전 요구사항

• Node.js 18.0.0 이상
• PromStack API Key (설정 > API Keys에서 발급)

2. 설치

npm install @promstack-1/mcp-server

3. CLI 실행

# 직접 실행
node bin/promstack-mcp.js --api-key YOUR_API_KEY

# 또는 환경 변수 사용
export PROMPTSTACK_API_KEY=YOUR_API_KEY
node bin/promstack-mcp.js

⚙️ Claude Desktop 설정

Claude Desktop 설정 파일 로드:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "promstack": {
      "command": "node",
      "args": [
        "D:/workspace/Prompt-Manager/mcp-server/bin/promstack-mcp.js",
        "--api-key",
        "YOUR_PK_LIVE_KEY"
      ]
    }
  }
}

주의: args의 경로는 실제 mcp-server가 위치한 절대 경로로 수정해야 합니다.

🛠️ 제공 도구 (Tools)

1. list_prompts

프로젝트의 프롬프트 목록을 조회합니다.

결과에는 각 프롬프트의 ID, 제목, 설명, 필요한 변수가 포함됩니다. projectId를 지정하지 않으면 API Key에 연결된 모든 프로젝트의 프롬프트를 반환합니다.

Parameters:

• projectId (optional): 특정 프로젝트의 프롬프트만 조회
• search (optional): 검색어로 필터링
• limit (optional): 최대 결과 수 (기본: 20, 최대: 100)

예시:

list_prompts({})                           // 전체 프롬프트 목록
list_prompts({ projectId: 5 })             // 특정 프로젝트만
list_prompts({ search: "마케팅" })          // 검색

---

2. get_prompt

특정 프롬프트의 상세 정보를 조회합니다.

프롬프트 ID를 지정하면 해당 프롬프트의 전체 내용, 시스템 프롬프트, 필요한 변수 등을 반환합니다. 프롬프트를 실행하기 전에 상세 내용을 확인할 때 유용합니다.

Parameters:

• promptId (required): 조회할 프롬프트 ID

예시:

get_prompt({ promptId: 42 })

---

3. select_prompt

작업 설명을 분석하여 가장 적합한 프롬프트를 자동으로 추천합니다.

키워드 매칭을 사용하여 작업 설명과 유사한 프롬프트를 찾습니다. 추천 결과에는 각 프롬프트의 관련성 점수와 사용법이 포함됩니다.

Selection Process:

1. 작업 설명을 분석하여 키워드를 추출합니다
2. 제목, 설명, 카테고리 매칭 순으로 가중치를 적용합니다
3. 가장 관련성 높은 프롬프트를 반환합니다

중요: 첫 번째 추천 프롬프트(rank: 1)가 가장 적합한 선택입니다.

• 첫 번째 추천을 우선 사용하세요
• 여러 좋은 후보가 있으면 첫 번째를 선택하되, 다른 옵션도 참고 가능합니다
• 적합한 결과가 없으면 다른 키워드로 재검색하세요

Parameters:

• taskDescription (required): 수행하려는 작업에 대한 설명
• projectId (optional): 검색 범위를 특정 프로젝트로 제한
• topK (optional): 추천할 프롬프트 수 (기본: 3, 최대: 10)

예시:

select_prompt({ taskDescription: "마케팅 이메일 작성" })
select_prompt({ taskDescription: "API 인증 구현", projectId: 5 })

---

4. export_skill

프롬프트를 Claude Skills 형식(SKILL.md)으로 내보냅니다.

출력에는 YAML frontmatter(name, description)와 Markdown 본문이 포함됩니다. 이 형식은 Claude Desktop, Claude Code 등에서 스킬로 사용할 수 있습니다.

⚠️ 유료 기능: Plus/Pro 플랜에서만 사용 가능합니다.

Parameters:

• promptId (required): 내보낼 프롬프트 ID
• includeResources (optional): 참조 리소스 포함 여부 (기본: false)

예시:

export_skill({ promptId: 42 })
export_skill({ promptId: 42, includeResources: true })

---

5. query_context 🆕

프롬프트에 연결된 GitHub 저장소 또는 문서 URL에서 컨텍스트를 검색합니다.

연결된 소스에서 코드, 문서, README 등을 추출하여 반환합니다. 결과는 캐싱되어 반복 요청 시 빠르게 응답합니다 (TTL: 1시간).

특징:

• 10,000자 제한: Context7 호환 형식
• 자동 캐싱: 1시간 TTL로 반복 요청 최적화
• 다중 소스: GitHub 저장소 및 문서 URL 동시 지원

Parameters:

• promptId (required): 프롬프트 ID
• maxTokens (optional): 최대 토큰 수 (기본: 10000, 최대: 10000)
• refreshCache (optional): 캐시 무시하고 새로 가져오기 (기본: false)

Returns:

• 연결된 소스에서 추출한 컨텍스트 (최대 10,000자)
• 캐시 상태 정보 (cached: true/false)
• 소스별 문자 수 통계

예시:

query_context({ promptId: 42 })
query_context({ promptId: 42, maxTokens: 5000 })
query_context({ promptId: 42, refreshCache: true })

---

🏗️ 아키텍처

이 서버는 Proxy 역할을 수행합니다.

User -> MCP Client (Claude) -> MCP Server (Local) -> HTTP (JSON-RPC) -> PromStack Backend

• SDK: @modelcontextprotocol/sdk
• Transport: StdioServerTransport
• Validation: zod