Metadata-Version: 2.4
Name: mcp2skill-setup
Version: 0.1.0
Summary: Declarative setup CLI for FORCE Lab AI Agent Skills (reads skill-setup.yaml)
Project-URL: Homepage, https://github.com/force-lab/mcp2skill-setup
Project-URL: Repository, https://github.com/force-lab/mcp2skill-setup
License: MIT
Keywords: ai-agent,cli,mcp,mcp2cli,setup,skill
Requires-Python: >=3.10
Requires-Dist: click>=8
Requires-Dist: pyyaml>=6
Description-Content-Type: text/markdown

# mcp2skill-setup

**Declarative setup CLI for FORCE Lab AI Agent Skills.**

Eliminates duplicate `setup.py` scripts across AI Agent Skills by providing a unified
`mcp2skill-setup setup <skill-dir>` command that reads a `skill-setup.yaml` config file.

## Installation

```bash
pip install mcp2skill-setup
# or use without installing:
uvx mcp2skill-setup setup <skill-dir>
```

## Usage

```bash
# Initialize a skill (reads skill-dir/skill-setup.yaml)
uvx mcp2skill-setup setup ~/.claude/skills/hitl
uvx mcp2skill-setup setup ~/.claude/skills/tapd-story-intake

# List configured MCP bakes
uvx mcp2skill-setup list-bakes
```

## `skill-setup.yaml` Format

Each skill directory contains a `skill-setup.yaml` that declaratively describes:
- **env**: required environment variables and how to obtain them
- **bakes**: mcp2cli baked connections to create
- **verify**: post-setup verification steps

### Env fetch strategies

| Strategy | Description |
|---|---|
| `prompt` | Ask the user interactively |
| `playwright` | Auto-extract via headless browser (requires `npx`) |
| `ai-platform-config` | Auto-discover from Cursor / Claude Desktop MCP config |

### Example: hitl skill

```yaml
name: hitl
env:
  - key: HITL_CHAT_ID
    fetch: prompt
    prompt: "请输入企微群 Chat ID（格式: wrkXXXXX）"
    required: true
bakes:
  - name: hitl
    type: stdio
    command: "npx -y hitl-mcp --service-url https://hitl.woa.com/api --chat-id {HITL_CHAT_ID} --timeout 3600"
    clear_proxy: true
verify:
  - bake: hitl
    expect_tool: send-and-wait-reply
```

### Example: tapd-story-intake skill (Playwright auto-fetch + optional HITL)

```yaml
name: tapd-story-intake
env:
  - key: TAPD_ACCESS_TOKEN
    fetch: playwright
    url: "https://tapd.woa.com/platform/myhome#tab=tab-mytoken"
    pattern: "[a-f0-9]{40}"
    fallback: prompt
    prompt: "无法自动获取，请手动粘贴 TAPD token"
  - key: HITL_CHAT_ID
    fetch: prompt
    prompt: "请输入企微群 Chat ID（可选，留空跳过）"
    required: false
bakes:
  - name: tapd
    type: http
    url: "https://mcpgw.knot.woa.com/tapd/"
    auth_header: "X-Tapd-Access-Token:env:TAPD_ACCESS_TOKEN"
    transport: streamable
  - name: hitl
    type: stdio
    command: "npx -y hitl-mcp --service-url https://hitl.woa.com/api --chat-id {HITL_CHAT_ID} --timeout 3600"
    clear_proxy: true
    skip_if_empty: [HITL_CHAT_ID]
verify:
  - bake: tapd
    expect_list: true
```

### Example: mr-review skill (auto-discover gongfeng token)

```yaml
name: mr-review
env:
  - key: GONGFENG_ACCESS_TOKEN
    fetch: ai-platform-config
    server_hint: gongfeng
    fallback: prompt
    prompt: "请输入工蜂 Access Token"
    derive:
      - key: GONGFENG_AUTH_HEADER
        value: "Bearer {value}"
bakes:
  - name: gongfeng
    type: http
    url: "https://mcpgw.knot.woa.com/gongfeng"
    auth_header: "Authorization:env:GONGFENG_AUTH_HEADER"
    transport: streamable
verify:
  - bake: gongfeng
    tool: get-current-user
    expect_field: username
```

## Publishing

```bash
cd infra/mcp2skill
pip install hatch
hatch build && hatch publish   # requires PyPI token
```

## Development

```bash
pip install -e "."
mcp2skill-setup --help
mcp2skill-setup setup path/to/skill
```
