@steercards/agent-tools 0.0.0-stage → 0.1.1

package/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+작은 수정과 버그 보고도 환영합니다. 이 도구는 원격 Steercards MCP 서버에 연결하는 독립형 패키지입니다. 서버 기능과 도구 목록을 클라이언트에 고정하지 않는 설계를 유지하세요.
+
+## 로컬 개발
+
+Node.js 22 이상에서 실행합니다.
+
+```sh
+npm ci
+npm run check
+npm test
+npm run build
+npm pack --dry-run
+```
+
+테스트는 로컬 fixture를 사용합니다. 실제 키, 개인 워크스페이스 데이터, 네트워크 연결을 기본 테스트에 추가하지 마세요. 연결 테스트가 필요한 변경은 별도 테스트 계정과 최소한의 읽기 작업으로 확인하고 실행 범위를 PR에 기록하세요.
+
+## 변경 제안
+
+- 버그 보고에는 패키지·Node·OS·클라이언트 버전, 재현 명령과 예상·실제 결과를 적습니다. 키와 개인정보는 제거합니다.
+- PR에는 사용자가 겪는 문제, 변경 후 동작, 수행한 검사와 아직 확인하지 않은 클라이언트를 적습니다.
+- 도구 탐색·호출 변경은 로컬 MCP fixture로 검증합니다. 설정·파일 경로 변경은 Windows 경로와 공백이 있는 경로도 고려합니다.
+- CLI 플래그, 환경 변수, 설치 경로가 바뀌면 README와 Skill을 함께 갱신합니다.
+- `serve`의 stdout은 MCP 메시지 전용입니다. 진단 로그는 stderr로 출력하고 키를 노출하지 않습니다.
+- `setup`은 MCP 설정과 Skill을 함께 설치·업데이트합니다. Steercards 외 설정·주석·사용자 파일은 보존하고 관리 항목에 사용자 수정이 있으면 쓰기 전에 중단합니다. 임시 프로젝트와 격리한 홈 디렉터리에서 첫 설치, 재실행, 이전 버전 업데이트, 충돌, dry run과 쓰기 실패 복구를 검증하세요.
+- `.steercards/setup/` 기록의 버전·옵션·해시를 다음 업데이트의 기준으로 사용합니다. 실제 개인 설치 기록과 ZIP은 테스트 fixture나 커밋에 넣지 마세요.
+- `setup`은 키 없이 실행하고 `.env`를 생성·변경하지 않습니다. `config`는 설정 조각만 출력하며 개별 `skill install`은 사용자 수정 파일을 덮어쓰지 않습니다.
+
+변경 제안은 [공개 저장소](https://github.com/velody-ai/steercards-agent-tools)에 PR로 올려주세요. 보안 문제는 공개 이슈에 올리지 말고 [SECURITY.md](SECURITY.md)를 따릅니다.
+
+## 릴리스
+
+릴리스 담당자는 [npm 릴리스 안내](docs/releases.md)를 따릅니다. 버전 변경 PR을 main에 병합하고 실제 tarball을 검사한 뒤 일치하는 태그의 안정 버전 GitHub Release를 게시합니다. 일반 CI와 main 병합은 검증을 수행하고, Release 게시 이벤트가 npm trusted publishing을 실행합니다.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steercards contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,195 @@
-# Temporary Holding Version
+# Steercards Agent Tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Steercards의 전체 MCP 도구를 CLI와 에이전트에서 사용할 수 있게 하는 독립형 Node.js 도구입니다. MIT 라이선스이며 Node.js 22 이상이 필요합니다.
+
+- 원격 서버의 도구 목록·설명·입력 스키마를 실행 시 조회합니다. 도구 목록을 패키지에 고정하지 않습니다.
+- 기본 `compact` 모드는 검색 → 스키마 확인 → 호출 흐름으로 초기 도구 노출을 줄입니다.
+- `full` 모드는 원격 도구를 각각 노출합니다.
+- 프로젝트 `.env`를 읽는 STDIO MCP 서버, 단독 CLI, 설치 가능한 Skill을 함께 제공합니다.
+
+패키지 이름은 `@steercards/agent-tools`, 실행 명령은 `steercards`입니다. npm에서 설치하거나 소스에서 빌드해 사용할 수 있습니다.
+
+## 소스에서 설치
+
+소스 디렉터리에서 빌드한 뒤 `setup --local`을 실행합니다.
+
+```sh
+npm ci
+npm run build
+node /absolute/path/agent-tools/dist/cli.js setup --client codex-app --cwd /absolute/path/project --local
+```
+
+`setup` 한 번으로 Steercards MCP 설정과 Skill을 함께 설치합니다. 키 없이 설치할 수 있으며 `.env`를 만들거나 덮어쓰지 않습니다. 설치 뒤 프로젝트에 `.env.example`을 참고한 `.env`를 만들고 실제 Agent Key를 입력하세요.
+
+```dotenv
+STEERCARDS_AGENT_KEY=your-agent-key
+# 기본값을 사용할 때는 생략합니다.
+STEERCARDS_MCP_URL=https://steercards.com/api/mcp
+```
+
+프로젝트 `.gitignore`에 `.env`와 `.steercards/`를 추가하세요. `.steercards/`에는 프로젝트별 설치 기록과 Desktop용 Skill ZIP이 들어갑니다. 설치 기록은 다음 업데이트에 필요한 로컬 소유권 정보이므로 보존하세요. 절대 경로를 포함하므로 다른 프로젝트·컴퓨터로 복사하거나 프로젝트 이동 후 그대로 재사용할 수 없습니다.
+
+클라이언트에서 필요한 MCP 승인과 재시작·다시 연결을 마친 뒤 확인합니다.
+
+```sh
+node /absolute/path/agent-tools/dist/cli.js doctor --cwd /absolute/path/project --connect
+```
+
+`doctor`는 키 값을 출력하지 않습니다. `--connect`를 추가하면 원격 서버에 연결하고 워크스페이스 목록을 조회하는 읽기 전용 검사를 수행합니다. 생략하면 로컬 설정만 확인합니다.
+
+## npm 설치와 업데이트
+
+처음 설치할 때와 새 버전으로 업데이트할 때 같은 명령을 사용합니다.
+
+```sh
+npx -y @steercards/agent-tools@latest setup --client codex-app --cwd /absolute/path/project
+```
+
+실행한 패키지 버전의 MCP 설정과 Skill을 함께 적용합니다. npx 기반 MCP 실행 명령은 해당 버전에 고정되므로 Skill과 같은 버전을 사용합니다. 같은 버전·옵션으로 다시 실행하면 변경 없이 성공합니다. 기존 설치에서는 생략한 실행 옵션(`--local`, `--mode`, `--url`, `--env-file`)을 설치 기록에서 유지합니다. `--local` 설치는 새 소스를 받은 뒤 `npm ci`, `npm run build`를 실행하고 같은 `setup --local` 명령을 다시 실행하세요.
+
+소스의 `--local` 설치를 npm 실행 방식으로 전환할 때는 `--npx`를 지정합니다. 이후 MCP 설정은 실행한 패키지 버전의 npx 명령을 사용합니다.
+
+```sh
+npx -y @steercards/agent-tools@latest setup --client codex-app --cwd /absolute/path/project --npx
+```
+
+전역 설치를 선택했다면 패키지를 업데이트한 뒤 `setup`을 다시 실행합니다.
+
+```sh
+npm install --global @steercards/agent-tools@latest
+steercards setup --client codex-app --cwd /absolute/path/project
+```
+
+이하 `steercards` 명령은 전역 설치를 기준으로 합니다. 소스 빌드 사용자는 `node /absolute/path/agent-tools/dist/cli.js`로 대체하면 됩니다.
+
+## 환경 설정
+
+| 설정 | 동작 |
+| --- | --- |
+| `STEERCARDS_AGENT_KEY` | Steercards Agent Key. 원격 요청에 필요합니다. |
+| `STEERCARDS_MCP_URL` | 선택 사항. 기본값은 `https://steercards.com/api/mcp`입니다. |
+| `--cwd PATH` | 프로젝트 디렉터리를 고정합니다. 생략하면 프로세스의 현재 디렉터리를 사용합니다. |
+| `--env-file PATH` | 기본 `.env` 대신 읽을 파일입니다. 상대 경로는 `--cwd` 기준입니다. |
+| `--url URL` | 이번 실행의 MCP URL을 지정합니다. 환경 변수보다 우선합니다. |
+
+이미 설정된 프로세스 환경 변수가 `.env`보다 우선합니다. 기본 `.env`는 지정한 디렉터리에서만 찾으며 상위 디렉터리를 탐색하지 않습니다. dotenv 값에 셸 명령이나 `${VARIABLE}` 확장을 수행하지 않습니다. 원격 URL은 HTTPS를 사용하며 로컬 개발용 loopback 주소만 HTTP를 허용합니다. URL의 인증 정보·쿼리·fragment는 허용하지 않습니다.
+
+GUI 앱은 터미널과 다른 디렉터리·환경에서 시작될 수 있습니다. 설정을 생성할 때 `--cwd`에 실제 프로젝트의 절대 경로를 지정하세요. 여러 프로젝트를 사용하면 서버 이름과 `--cwd`를 프로젝트별로 구분하세요. 키는 MCP 설정에 복사하지 않고 해당 프로젝트의 `.env`에 둡니다.
+
+## 클라이언트 설치·업데이트
+
+```sh
+steercards setup --client codex-app --cwd /absolute/path/project
+steercards setup --client claude-code --cwd /absolute/path/project
+steercards setup --client cursor --cwd /absolute/path/project
+steercards setup --client claude-desktop --cwd /absolute/path/project
+```
+
+TTY에서 `--client`를 생략하면 사용할 클라이언트를 선택합니다. CI·스크립트 등 대화형 입력을 사용할 수 없는 환경에서는 `--client`를 지정해야 합니다. `codex`, `codex-app`, `codex-cli`는 같은 Codex 설치 위치를 사용합니다.
+
+| 클라이언트 | `--client` | MCP 설정과 Skill 설치 위치 |
+| --- | --- | --- |
+| Codex 앱·CLI | `codex`, `codex-app`, `codex-cli` | 프로젝트 `.codex/config.toml`과 `.agents/skills/steercards/`. 프로젝트 설정은 신뢰한 프로젝트에서 사용합니다. [공식 MCP 설정](https://developers.openai.com/codex/mcp), [Skills](https://developers.openai.com/codex/skills) |
+| Claude Code | `claude-code` | 프로젝트 `.mcp.json`과 `.claude/skills/steercards/`. [공식 MCP 설정](https://code.claude.com/docs/en/mcp), [Skills](https://code.claude.com/docs/en/skills) |
+| Cursor | `cursor` | 프로젝트 `.cursor/mcp.json`과 `.cursor/skills/steercards/`. [공식 MCP 설정](https://cursor.com/docs/mcp), [Skills](https://cursor.com/docs/skills) |
+| Claude Desktop | `claude-desktop` | 아래 OS별 사용자 MCP 설정과 프로젝트 `.steercards/steercards-skill.zip`. [로컬 MCP 연결 안내](https://modelcontextprotocol.io/docs/develop/connect-local-servers) |
+
+Claude Desktop 자동 설치는 macOS와 Windows를 지원합니다. MCP 설정은 macOS의 `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows의 `%APPDATA%\Claude\claude_desktop_config.json`에 병합합니다. Desktop은 사용자 설정이므로 선택한 프로젝트의 `--cwd`가 연결 대상이 됩니다. 생성한 ZIP은 앱의 Skill 업로드 UI에서 직접 추가해야 하며 업데이트 후에는 새 ZIP을 다시 업로드합니다. 계정·앱의 업로드 지원 여부는 [Claude 공식 Skill 안내](https://support.claude.com/en/articles/12512180-use-skills-in-claude)를 확인하세요.
+
+소스에서 빌드한 경우 `--local`을 사용하세요. 실제 Node 실행 파일과 `dist/cli.js`의 절대 경로를 MCP 설정에 넣으므로 해당 설치 디렉터리를 유지해야 합니다. Windows GUI에서도 실행 경로를 확실히 고정하는 이 방식을 권장합니다. `--local`을 생략한 설정은 `npx`를 사용하므로 클라이언트에서 `npx`를 실행할 수 있어야 합니다.
+
+지원 옵션:
+
+```sh
+steercards setup [--client CLIENT] [--local | --npx] [--dry-run] [--cwd PATH] [--env-file PATH] [--url URL] [--mode compact|full]
+```
+
+`--dry-run`은 파일을 쓰지 않고 예정된 작업만 보여줍니다. 키를 출력하거나 연결 검사를 수행하지 않습니다. `setup`은 코드 클라이언트를 프로젝트 범위에 설치하며 `--global`을 지원하지 않습니다. `--env-file`, `--url`, `--mode`는 생성할 MCP 실행 옵션에도 반영됩니다. 같은 버전에서도 옵션을 바꾸면 해당 설정을 갱신합니다. `--local`과 `--npx`는 함께 사용할 수 없으며 `--npx`는 `setup` 전용 옵션입니다.
+
+```sh
+steercards setup --client cursor --cwd /absolute/path/project --dry-run
+```
+
+`setup`은 기존 설정의 Steercards MCP 항목만 병합하고 다른 서버·설정·주석과 사용자 파일은 보존합니다. `.steercards/setup/*.json`에 설치한 버전·옵션과 관리 파일의 해시를 기록하여 다음 업데이트에서 비교합니다. 관리 기록 없이 이전 `config`·`skill install` 명령으로 설치한 경우에도 현재 생성할 MCP 관리 필드와 Skill 파일이 같으면 관리 대상으로 등록합니다. Codex TOML은 이전 `config`의 정확한 출력 형식이어야 합니다. 그 외의 기존 충돌 항목이나 사용자가 수정한 관리 설정·Skill이 있으면 파일을 쓰기 전에 중단합니다. 충돌 시 수정 내용을 별도로 보관하고 기존 항목과 설치 기록을 검토한 뒤 수동 병합하거나 다시 설치하세요. 일반적인 쓰기 실패는 이전 파일로 복구하지만 전원 차단까지 포함한 원자적 저장을 보장하지 않습니다.
+
+기본 `compact` 모드가 노출하는 도구는 다음 네 개입니다.
+
+| 도구 | 용도 |
+| --- | --- |
+| `steercards_search_tools` | 필요한 원격 도구 검색 |
+| `steercards_describe_tool` | 선택한 도구의 설명·입력 스키마 확인 |
+| `steercards_call_tool` | 확인한 이름과 인자로 원격 도구 호출 |
+| `steercards_get_guide` | Steercards 사용 가이드 조회 |
+
+클라이언트가 개별 도구 노출을 필요로 하면 `setup`에 `--mode full`을 추가하세요.
+
+```sh
+steercards setup --client codex-app --cwd /absolute/path/project --mode full
+steercards serve --cwd /absolute/path/project --mode full
+```
+
+`compact` 모드의 호출 도구는 여러 종류의 쓰기 작업도 실행할 수 있습니다. 도구 수를 줄이는 기능이며 접근 권한을 제한하지 않습니다. `full` 모드는 원격 도구 이름·스키마·메타데이터를 직접 노출하므로 클라이언트에서 개별 도구를 다루기 쉽습니다. 원격 도구의 메타데이터와 호출 결과의 `isError`·`structuredContent` 오류 신호를 보존합니다. 실제 사용 범위는 Agent Key의 서버 권한으로 결정됩니다.
+
+## CLI로 도구 사용
+
+먼저 검색 결과에서 정확한 도구 이름을 찾고 스키마를 확인한 뒤 호출합니다. 이름·필수 인자·사용 가능한 기능은 연결한 서버에서 조회한 결과를 따릅니다.
+
+```sh
+steercards tools workspace --limit 10 --cwd /absolute/path/project
+steercards describe <tool-name> --cwd /absolute/path/project
+steercards call <tool-name> --json '{"workspaceId":1}' --cwd /absolute/path/project
+steercards call <tool-name> --file ./arguments.json --cwd /absolute/path/project
+steercards call <tool-name> --stdin --cwd /absolute/path/project < arguments.json
+```
+
+`<tool-name>`과 JSON은 조회한 스키마에 맞게 바꿉니다. `--json`, `--file`, `--stdin`은 하나만 사용하며 모두 생략하면 `{}`를 전달합니다. 셸 기록에 남길 수 없는 내용은 파일 또는 표준 입력으로 전달하세요. 호출 결과에는 실제 워크스페이스 데이터가 포함될 수 있습니다. CLI는 JSON 결과를 출력하고 프로토콜·제품 오류 시 0이 아닌 종료 코드를 반환합니다. 쓰기 요청은 자동 재시도하지 않습니다.
+
+`serve`는 MCP STDIO 연결용입니다. 터미널에서 직접 실행하면 클라이언트 입력을 기다리는 것이 정상입니다.
+
+## 고급: 설정 조각과 Skill 개별 설치
+
+기본 설치·업데이트에는 `setup`을 사용하세요. 직접 설정을 관리하려면 기존 개별 명령도 사용할 수 있습니다.
+
+```sh
+steercards config codex-app --cwd /absolute/path/project
+steercards config cursor --cwd /absolute/path/project --local
+steercards skill install --client codex --cwd /absolute/path/project
+steercards skill install --client claude-code --cwd /absolute/path/project
+steercards skill install --client cursor --cwd /absolute/path/project
+steercards skill export --output /absolute/path/steercards-skill.zip
+```
+
+`config`는 설정 조각만 출력하며 클라이언트 설정을 수정하지 않습니다. 출력 내용을 기존 파일에 수동 병합해야 합니다. `skill install --global`은 사용자 홈 아래의 해당 클라이언트 Skill 디렉터리에 개별 설치합니다. 개별 Skill 설치는 같은 내용이면 성공하고 변경된 기존 디렉터리는 덮어쓰지 않습니다. 이 명령들은 MCP·Skill을 함께 갱신하거나 `setup`의 관리 기록을 만들지 않습니다.
+
+Skill은 도구 탐색 순서와 작업 요령을 제공합니다. `compact` 모드에서는 Skill을 업로드하지 않아도 `steercards_get_guide` 도구로 가이드를 읽을 수 있습니다. `full` 모드는 이 도구를 추가하지 않으며, `steercards://guide/overview`와 주제별 MCP resource를 제공합니다. Claude Desktop에서 `full` 모드를 사용할 때는 Skill ZIP을 업로드하거나, 클라이언트가 resource 읽기를 지원하는 경우 해당 resource로 가이드를 읽으세요.
+
+## 검증 범위와 문제 해결
+
+공통 MCP 프로토콜과 로컬 CLI·설정 생성은 로컬 fixture 자동 테스트로 검증합니다. 2026-10-19에는 MCP SDK로 실제 STDIO 서버에 연결해 `compact`의 4개 도구와 `full`의 141개 원격 도구를 확인했고, 두 모드에서 `list_workspaces` 읽기 호출이 성공했습니다. 원격 도구 수는 서버와 Agent Key 권한에 따라 달라집니다.
+
+Claude Code, Codex 앱·CLI, Cursor, Claude Desktop 각각의 네이티브 UI 연결을 모두 검증한 것은 아닙니다. 로컬 자동 테스트·실제 STDIO 연결 검증·CI의 OS별 실행·개별 앱에서의 연결 확인은 서로 다른 검증 범위입니다.
+
+- 인증 오류: `doctor --cwd …`로 키 탐지 여부를 확인하고 `doctor --connect`로 읽기 전용 연결을 검사하세요. 키 값은 보고서나 이슈에 붙이지 마세요.
+- GUI에서만 실행 실패: Node 22 이상을 설치하고 `--local` 설정을 다시 생성해 절대 실행 경로와 `--cwd`를 확인하세요.
+- 도구가 보이지 않음: MCP 서버를 다시 연결하고 `tools`로 원격 목록을 확인하세요. 특정 키에 없는 권한을 이 패키지가 추가하지는 않습니다.
+- 설치 충돌: `setup --dry-run`으로 예정된 작업을 확인하고 `.steercards/setup/` 기록과 기존 Steercards 항목·Skill 수정 사항을 검토하세요. 기존 파일을 통째로 교체하거나 관리 기록만 지워서 업데이트를 강제하지 마세요.
+
+## 개발·기여·릴리스
+
+```sh
+npm ci
+npm run check
+npm test
+npm run build
+npm pack --dry-run
+```
+
+CI는 Linux·macOS·Windows의 Node 22·24에서 같은 검사를 실행합니다. 테스트는 로컬 fixture를 사용하며 실제 Agent Key가 필요하지 않습니다. 기여 방법은 [CONTRIBUTING.md](CONTRIBUTING.md), 보안 보고는 [SECURITY.md](SECURITY.md)를 참고하세요.
+
+공개 소스는 [velody-ai/steercards-agent-tools](https://github.com/velody-ai/steercards-agent-tools)에서 관리합니다. 안정 버전 GitHub Release를 게시하면 `publish.yml`이 태그·패키지 버전과 main 포함 여부를 확인하고 검사를 다시 실행한 뒤 npm에 게시합니다. 인증은 GitHub OIDC trusted publishing을 사용하며 공개 패키지에 provenance를 연결합니다.
+
+최초 npm 설정, 릴리스 명령, 게시·설치 확인과 실패 대응은 [npm 릴리스 안내](docs/releases.md)를 따릅니다.
+
+## 라이선스
+
+[MIT](LICENSE), Copyright (c) 2026 Steercards contributors.

package/SECURITY.md

@@ -0,0 +1,28 @@
+# Security
+
+## 보안 문제 보고
+
+취약점, Agent Key 노출, 의도하지 않은 파일 덮어쓰기 또는 인증 경계를 우회하는 동작을 발견하면 실제 키와 워크스페이스 데이터를 공개 이슈에 올리지 마세요.
+
+공개 저장소가 마련되고 GitHub private vulnerability reporting이 활성화되면 저장소의 **Security → Report a vulnerability**로 비공개 보고합니다. 그 기능이 없거나 소스를 직접 전달받았다면 유지관리자에게 기존 비공개 연락 경로로 보고 방법을 요청하세요. 전용 보안 이메일이나 응답 기한은 아직 지정하지 않았습니다. 첫 공개 릴리스 전에 실제 비공개 보고 경로를 확정해야 합니다.
+
+보고에는 영향받는 버전, 재현 조건, 비밀값을 제거한 최소 재현과 예상 영향을 포함하세요. 노출된 키는 Steercards에서 폐기·재발급하고 로그·저장소·공유 자료에 남은 값을 제거하세요.
+
+## 로컬 설치 파일
+
+`setup`은 선택한 클라이언트의 Steercards MCP 설정과 Skill을 함께 설치·업데이트합니다. 코드 클라이언트는 프로젝트 설정에 쓰고, Claude Desktop은 OS 사용자 MCP 설정에 병합한 뒤 프로젝트에 Skill ZIP을 만듭니다. 앱의 승인·재시작과 Desktop Skill 업로드는 사용자가 진행합니다.
+
+설치에는 Agent Key가 필요하지 않으며 `.env`를 만들거나 덮어쓰지 않습니다. `--dry-run`은 쓰기 없이 예정 작업을 보여줍니다. `.steercards/setup/*.json`에는 설치한 버전·실행 옵션·관리 파일의 해시가 들어갑니다. 키는 저장하지 않지만 로컬 경로와 서버 주소가 포함될 수 있으므로 프로젝트 `.gitignore`에 `.steercards/`를 추가하고 설치 기록을 다른 프로젝트·컴퓨터로 복사하지 마세요. 절대 경로가 달라진 설치에는 해당 기록을 그대로 재사용할 수 없습니다.
+
+다른 MCP 설정·주석·사용자 파일은 보존합니다. 이전 개별 설치의 MCP 관리 필드와 Skill 파일이 현재 생성할 내용과 일치하면 관리 기록을 만들 수 있습니다. 그 외의 관리 기록 없는 충돌이나 관리 설정·Skill의 사용자 수정은 쓰기 전에 거부합니다. 일반적인 쓰기 실패 시 복구를 시도하지만 전원 차단 등 모든 중단에서 원자적 복구를 보장하지 않습니다. 중요한 사용자 설정은 별도로 백업하세요.
+
+## 인증과 데이터
+
+- `STEERCARDS_AGENT_KEY`는 로컬 환경 변수 또는 프로젝트 `.env`로 공급합니다. Git, MCP 설정 조각, 이슈, 프롬프트에 키를 붙이지 마세요.
+- 프로젝트 `.env`는 지정한 `--cwd`에서 읽습니다. 신뢰할 수 있는 프로젝트와 환경 파일만 사용하세요.
+- 요청은 설정한 MCP URL로 전송됩니다. `--url`이나 `STEERCARDS_MCP_URL`을 바꿀 때는 신뢰하는 서버인지 확인하세요.
+- Agent Key의 권한과 접근 가능한 워크스페이스는 원격 Steercards 서버가 결정합니다. 이 패키지는 별도 계정·워크스페이스 권한을 부여하지 않습니다.
+- `compact` 모드의 범용 호출 도구는 쓰기와 삭제를 포함한 원격 기능을 실행할 수 있습니다. 읽기 전용 모드나 권한 샌드박스가 아닙니다. 클라이언트의 도구 승인 정책을 사용하고 호출 전에 실제 스키마와 대상을 확인하세요.
+- 도구 결과에는 사용자 데이터가 들어갈 수 있습니다. 키 마스킹만으로 모든 출력의 개인정보가 제거되는 것은 아닙니다.
+
+초기 0.1.x 단계에서는 최신 공개 릴리스에 수정 사항을 제공하는 것을 목표로 합니다. 별도 장기 지원 브랜치나 서비스 수준 보장은 없습니다.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { loadConfig } from './config.js';
+import { Runtime } from './runtime.js';
+import { startServer } from './server.js';
+import { clientConfig, installSkill, exportSkill, packageInfo } from './install.js';
+import { setup } from './setup.js';
+const help = `Steercards agent tools ${packageInfo.version}
+
+steercards setup [--client CLIENT] [--local | --npx] [--dry-run]
+steercards serve [--mode compact|full]
+steercards tools [query] [--limit 10]
+steercards describe NAME
+steercards call NAME [--json JSON | --file PATH | --stdin]
+steercards doctor [--connect]
+steercards config CLIENT [--local] [--mode compact|full]
+steercards skill install --client CLIENT [--global]
+steercards skill export --output PATH.zip
+
+Connection options: --cwd PATH --env-file PATH --url URL
+Default .env: exactly --cwd/.env (otherwise current directory).
+Environment: STEERCARDS_AGENT_KEY, optional STEERCARDS_MCP_URL.
+Clients: claude-code, codex, codex-app, codex-cli, cursor, claude-desktop.
+setup installs MCP configuration and the skill together; rerun to update both.
+setup uses project scope (Desktop uses its user configuration and a project ZIP).
+--npx explicitly switches an existing local setup to a pinned npm package.
+--dry-run previews setup without writing files. No key is needed for setup.
+config only prints a snippet and never edits host settings.
+--local uses this installation's absolute Node/CLI paths (works before npm release).
+Claude Desktop: upload the skill ZIP, use compact get_guide, or full guide resources.
+Full tool responses are JSON; tool/product errors exit nonzero. Writes are never retried.
+`;
+function output(value) { process.stdout.write(JSON.stringify(value, null, 2) + '\n'); }
+function isFailure(result) {
+    if (!result || typeof result !== 'object')
+        return false;
+    const r = result;
+    if (r.isError === true || r.structuredContent?.ok === false)
+        return true;
+    if (Array.isArray(r.content))
+        for (const item of r.content) {
+            if (item.type === 'text') {
+                try {
+                    if (JSON.parse(item.text)?.ok === false)
+                        return true;
+                }
+                catch { }
+            }
+        }
+    return false;
+}
+async function stdinText() {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.length;
+        if (size > 7 * 1024 * 1024)
+            throw new Error('JSON input exceeds 7 MiB.');
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+let secret = process.env.STEERCARDS_AGENT_KEY;
+async function main() {
+    const { values, positionals } = parseArgs({ allowPositionals: true, strict: true, options: {
+            cwd: { type: 'string' }, 'env-file': { type: 'string' }, url: { type: 'string' }, mode: { type: 'string' },
+            json: { type: 'string' }, file: { type: 'string' }, stdin: { type: 'boolean' },
+            client: { type: 'string' }, global: { type: 'boolean' }, output: { type: 'string' },
+            limit: { type: 'string' }, connect: { type: 'boolean' }, local: { type: 'boolean' },
+            'dry-run': { type: 'boolean' }, npx: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' },
+        } });
+    if (values.version) {
+        process.stdout.write(packageInfo.version + '\n');
+        return;
+    }
+    if (values.help || positionals.length === 0) {
+        process.stdout.write(help);
+        return;
+    }
+    const [command, name, ...extra] = positionals;
+    const options = { cwd: values.cwd, envFile: values['env-file'], url: values.url };
+    if (extra.length)
+        throw new Error('Unexpected extra arguments. Use --help.');
+    if (command === 'setup') {
+        if (name)
+            throw new Error('Use setup --client CLIENT.');
+        for (const option of ['json', 'file', 'stdin', 'limit', 'output', 'connect']) {
+            if (values[option] !== undefined)
+                throw new Error(`--${option} is not supported by setup.`);
+        }
+        if (values.global)
+            throw new Error('setup uses project scope; omit --global. Claude Desktop configuration is user-scoped.');
+        if (values.local && values.npx)
+            throw new Error('Choose only one of --local or --npx.');
+        let client = values.client;
+        if (!client) {
+            if (!process.stdin.isTTY || !process.stderr.isTTY)
+                throw new Error('Noninteractive setup requires --client: codex, claude-code, cursor, or claude-desktop.');
+            const choices = ['codex', 'claude-code', 'cursor', 'claude-desktop'];
+            const prompt = createInterface({ input: process.stdin, output: process.stderr });
+            try {
+                process.stderr.write('Choose a client:\n1. Codex app / CLI\n2. Claude Code\n3. Cursor\n4. Claude Desktop\n');
+                const answer = (await prompt.question('Client [1-4 or name]: ')).trim();
+                client = /^[1-4]$/.test(answer) ? choices[Number(answer) - 1] : answer;
+            }
+            finally {
+                prompt.close();
+            }
+            if (!client)
+                throw new Error('No client selected. Nothing was installed.');
+        }
+        output(await setup({ ...options, client, local: values.npx ? false : values.local, mode: values.mode, dryRun: values['dry-run'] }));
+        return;
+    }
+    if (values['dry-run'] || values.npx)
+        throw new Error('--dry-run and --npx are only supported by setup.');
+    if (command === 'config') {
+        if (!name)
+            throw new Error('Choose a client. Use --help.');
+        process.stdout.write(clientConfig(name, { ...options, local: values.local, mode: values.mode }));
+        return;
+    }
+    if (command === 'skill') {
+        if (name === 'install') {
+            if (!values.client)
+                throw new Error('skill install requires --client.');
+            output(await installSkill({ client: values.client, cwd: values.cwd, global: values.global }));
+            return;
+        }
+        if (name === 'export') {
+            if (!values.output)
+                throw new Error('skill export requires --output PATH.zip.');
+            output({ path: await exportSkill(resolve(values.cwd ?? process.cwd(), values.output)) });
+            return;
+        }
+        throw new Error('Use skill install or skill export.');
+    }
+    if (!['serve', 'tools', 'describe', 'call', 'doctor'].includes(command))
+        throw new Error('Unknown command. Use --help.');
+    if (['serve', 'doctor'].includes(command) && name)
+        throw new Error('Unexpected positional argument.');
+    if (['describe', 'call'].includes(command) && !name)
+        throw new Error(`${command} requires a tool name.`);
+    if (values.mode && !['compact', 'full'].includes(values.mode))
+        throw new Error('Mode must be compact or full.');
+    const limit = values.limit === undefined ? 10 : Number(values.limit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw new Error('--limit must be an integer from 1 to 100.');
+    let args = {};
+    if (command === 'call') {
+        if ([values.json !== undefined, values.file !== undefined, values.stdin === true].filter(Boolean).length > 1)
+            throw new Error('Choose only one of --json, --file, or --stdin.');
+        const source = values.json ?? (values.file !== undefined ? await readFile(resolve(values.cwd ?? process.cwd(), values.file), 'utf8') : values.stdin ? await stdinText() : '{}');
+        if (Buffer.byteLength(source) > 7 * 1024 * 1024)
+            throw new Error('JSON input exceeds 7 MiB.');
+        try {
+            args = JSON.parse(source);
+        }
+        catch {
+            throw new Error('Invalid JSON arguments.');
+        }
+        if (args === null || typeof args !== 'object' || Array.isArray(args))
+            throw new Error('Tool arguments must be a JSON object.');
+    }
+    const config = await loadConfig(options);
+    secret = config.agentKey;
+    if (command === 'doctor' && !values.connect) {
+        output({ ok: true, cwd: config.cwd, envFile: config.envFile, url: config.url, keySource: config.keySource, keyPresent: true, connected: false });
+        return;
+    }
+    const runtime = new Runtime(config);
+    if (command === 'serve') {
+        const server = await startServer(runtime, { mode: (values.mode ?? 'compact') });
+        let closing = false;
+        const close = async () => { if (closing)
+            return; closing = true; await server.close(); await runtime.close(); };
+        process.once('SIGINT', () => { void close(); });
+        process.once('SIGTERM', () => { void close(); });
+        return;
+    }
+    try {
+        if (command === 'tools') {
+            output(name ? await runtime.searchTools(name, limit) : (await runtime.listTools()).map(tool => ({ name: tool.name, description: tool.description?.split('\n')[0] })));
+            return;
+        }
+        if (command === 'describe') {
+            output(await runtime.describeTool(name));
+            return;
+        }
+        if (command === 'doctor') {
+            const catalog = await runtime.listTools();
+            const result = await runtime.callTool('list_workspaces', {});
+            output({ ok: !isFailure(result), connected: !isFailure(result), toolCount: catalog.length, keySource: config.keySource, result });
+            if (isFailure(result))
+                process.exitCode = 1;
+            return;
+        }
+        const result = await runtime.callTool(name, args);
+        output(result);
+        if (isFailure(result))
+            process.exitCode = 1;
+    }
+    finally {
+        await runtime.close();
+    }
+}
+main().catch(error => {
+    const message = error instanceof Error ? error.message : 'Unexpected failure.';
+    const safe = secret ? message.split(secret).join('[REDACTED]') : message;
+    process.stderr.write(JSON.stringify({ ok: false, error: safe }) + '\n');
+    process.exitCode = 1;
+});

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+/** Verified against the product HTTP route and production deployment workflow. */
+export declare const DEFAULT_MCP_URL = "https://steercards.com/api/mcp";
+export interface Config {
+    url: string;
+    agentKey: string;
+    cwd: string;
+    envFile: string;
+    keySource: 'environment' | 'env-file';
+}
+export interface ConfigOptions {
+    cwd?: string;
+    envFile?: string;
+    url?: string;
+    /** Supply an isolated environment for embedding or tests. Never mutated. */
+    env?: NodeJS.ProcessEnv;
+}
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare function validateMcpUrl(value: string): string;
+/** Read one selected file only; do not traverse parents or hydrate process.env. */
+export declare function loadConfig(options?: ConfigOptions): Promise<Config>;

package/dist/config.js

@@ -0,0 +1,58 @@
+import { readFile, stat } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import { parse } from 'dotenv';
+/** Verified against the product HTTP route and production deployment workflow. */
+export const DEFAULT_MCP_URL = 'https://steercards.com/api/mcp';
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+export function validateMcpUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new ConfigError('STEERCARDS_MCP_URL must be an absolute HTTP(S) URL.');
+    }
+    if (url.username || url.password || url.search || url.hash) {
+        throw new ConfigError('STEERCARDS_MCP_URL must not contain credentials, a query, or a fragment.');
+    }
+    const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
+        throw new ConfigError('STEERCARDS_MCP_URL requires HTTPS, except for localhost.');
+    }
+    return url.href;
+}
+/** Read one selected file only; do not traverse parents or hydrate process.env. */
+export async function loadConfig(options = {}) {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    try {
+        if (!(await stat(cwd)).isDirectory())
+            throw new Error();
+    }
+    catch {
+        throw new ConfigError('The selected working directory does not exist or is not a directory.');
+    }
+    const envFile = options.envFile && isAbsolute(options.envFile)
+        ? options.envFile : resolve(cwd, options.envFile ?? '.env');
+    let file = {};
+    try {
+        file = parse(await readFile(envFile));
+    }
+    catch (error) {
+        if (options.envFile !== undefined || error.code !== 'ENOENT') {
+            throw new ConfigError('Unable to read the selected environment file.');
+        }
+    }
+    const env = options.env ?? process.env;
+    const fromEnvironment = env.STEERCARDS_AGENT_KEY !== undefined;
+    const agentKey = fromEnvironment ? env.STEERCARDS_AGENT_KEY : file.STEERCARDS_AGENT_KEY;
+    if (!agentKey || /\s/.test(agentKey)) {
+        throw new ConfigError('Set STEERCARDS_AGENT_KEY to a nonempty Agent Key without whitespace.');
+    }
+    const url = validateMcpUrl(options.url ?? env.STEERCARDS_MCP_URL ?? file.STEERCARDS_MCP_URL ?? DEFAULT_MCP_URL);
+    return { url, agentKey, cwd, envFile, keySource: fromEnvironment ? 'environment' : 'env-file' };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { loadConfig } from './config.js';
+export { Runtime } from './runtime.js';
+export { createServer, startServer } from './server.js';
+export type { Config, ConfigOptions } from './config.js';
+export type { ToolSummary } from './runtime.js';
+export { getGuide } from './server.js';
+export { setup } from './setup.js';
+export type { SetupOptions, SetupReport } from './setup.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { loadConfig } from './config.js';
+export { Runtime } from './runtime.js';
+export { createServer, startServer } from './server.js';
+export { getGuide } from './server.js';
+export { setup } from './setup.js';

package/dist/install.d.ts

@@ -0,0 +1,22 @@
+export { packageRoot, packageInfo } from './package.js';
+export declare const skillRoot: string;
+export declare const clients: readonly ["claude-code", "codex", "codex-app", "codex-cli", "cursor", "claude-desktop"];
+export type Client = typeof clients[number];
+export declare function clientConfig(client: string, options?: {
+    cwd?: string;
+    local?: boolean;
+    mode?: string;
+    url?: string;
+    envFile?: string;
+}): string;
+export declare function installSkill(options: {
+    client: string;
+    cwd?: string;
+    global?: boolean;
+    home?: string;
+    source?: string;
+}): Promise<{
+    path: string;
+    status: 'installed' | 'unchanged';
+}>;
+export declare function exportSkill(output: string, source?: string): Promise<string>;