npm package: @promstack-1/mcp-server
Description: PromStack MCP Server - Connect Claude Desktop and other MCP clients to your prompts
Author: PromStack
Latest version: 1.0.2

# @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. 설치

```bash
npm install @promstack-1/mcp-server
```

### 3. CLI 실행

```bash
# 직접 실행
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`

```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`