{"_id":"@code3-team/spec-kit-mcp-adapter","name":"@code3-team/spec-kit-mcp-adapter","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@code3-team/spec-kit-mcp-adapter","version":"1.0.0","description":"Bounty flow adapter for spec-kit workflow - publish, accept, submit, confirm, and claim bounties on Ethereum/Aptos","type":"module","main":"./dist/server.js","bin":{"spec-kit-mcp-adapter":"dist/server.js"},"keywords":["mcp","bounty","ethereum","aptos","spec-kit","claude-code","web3"],"repository":{"type":"git","url":"git+https://github.com/cyl19970726/Code3.git","directory":"task3/adapters/spec-kit-mcp-adapter"},"author":{"name":"Code3 Team"},"license":"MIT","dependencies":{"@aptos-labs/ts-sdk":"^1.39.0","@modelcontextprotocol/sdk":"^1.0.4","@octokit/rest":"^21.0.2","ethers":"^6.15.0","yaml":"^2.3.0","zod":"^3.24.1"},"devDependencies":{"@types/node":"^22.18.10","@vitest/ui":"^3.2.4","dotenv":"^17.2.3","esbuild":"^0.25.11","typescript":"^5.7.2","vitest":"^3.2.4","@code3-team/bounty-operator":"1.0.0","@code3-team/bounty-operator-ethereum":"1.0.0","@code3-team/bounty-operator-aptos":"0.1.0","@code3-team/data-layers-github":"1.0.0","@code3-team/data-operator":"1.0.0","@code3-team/orchestration":"1.0.0"},"scripts":{"build":"node build.js","build:types":"tsc","start":"node dist/server.js","dev":"tsc --watch","test":"vitest run","test:watch":"vitest","test:ui":"vitest --ui","test:coverage":"vitest run --coverage","test:e2e":"vitest run tests/e2e-*.test.ts","test:e2e:watch":"vitest tests/e2e-*.test.ts"},"_id":"@code3-team/spec-kit-mcp-adapter@1.0.0","bugs":{"url":"https://github.com/cyl19970726/Code3/issues"},"homepage":"https://github.com/cyl19970726/Code3#readme","_integrity":"sha512-/RhYQ5pGmH7Zvbhrj9Hgonl32iFRxcO4NpWZjKeVKAWfSjNXKert+DYxalXa0nu8Tx7bg8qgO1MRA/uRMnQ6ag==","_resolved":"/private/var/folders/97/6ydtlhlx7750tcl9pk4kfx100000gn/T/67779254727e65159086dd4201d00d71/code3-team-spec-kit-mcp-adapter-1.0.0.tgz","_from":"file:code3-team-spec-kit-mcp-adapter-1.0.0.tgz","_nodeVersion":"23.0.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-/RhYQ5pGmH7Zvbhrj9Hgonl32iFRxcO4NpWZjKeVKAWfSjNXKert+DYxalXa0nu8Tx7bg8qgO1MRA/uRMnQ6ag==","shasum":"ada71fa7ddc079adb5970c3dc2b410aeec679cb2","tarball":"https://registry.npmjs.org/@code3-team/spec-kit-mcp-adapter/-/spec-kit-mcp-adapter-1.0.0.tgz","fileCount":3,"unpackedSize":77654,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFphWvD47r7acDb7HJ0rHkRbEr7SmH5SI2KkoTLpYR43AiAAvQsVahr9nP+EyYl/qPWvoB3SOQ1FQ8me1mjk+v3j2g=="}]},"_npmUser":{"name":"hhh_qc","email":"hhhquickcreation@gmail.com"},"directories":{},"maintainers":[{"name":"hhh_qc","email":"hhhquickcreation@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/spec-kit-mcp-adapter_1.0.0_1761022109988_0.36829880445435736"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-21T04:48:29.922Z","1.0.0":"2025-10-21T04:48:30.171Z","modified":"2025-10-21T04:48:30.445Z"},"maintainers":[{"name":"hhh_qc","email":"hhhquickcreation@gmail.com"}],"description":"Bounty flow adapter for spec-kit workflow - publish, accept, submit, confirm, and claim bounties on Ethereum/Aptos","homepage":"https://github.com/cyl19970726/Code3#readme","keywords":["mcp","bounty","ethereum","aptos","spec-kit","claude-code","web3"],"repository":{"type":"git","url":"git+https://github.com/cyl19970726/Code3.git","directory":"task3/adapters/spec-kit-mcp-adapter"},"author":{"name":"Code3 Team"},"bugs":{"url":"https://github.com/cyl19970726/Code3/issues"},"license":"MIT","readme":"# spec-kit-mcp-adapter\n\n> Bounty flow adapter for spec-kit workflow on Code3 platform\n\n## Overview\n\nThis adapter implements the **Bounty flow** for spec-kit workflow, enabling:\n- Publishing bounties to GitHub Issues and blockchain (Ethereum/Aptos)\n- Accepting and working on bounties\n- Submitting work via Pull Requests\n- Confirming submissions (with optional cooling period)\n- Claiming payouts after review\n\n**Separation of Concerns**:\n- This package: **Bounty lifecycle tools** (6 tools: guide, publish, accept, submit, confirm, claim)\n- [`spec-kit-mcp`](../../../workflows/spec-kit-mcp/): **Workflow tools** (7 tools: specify, analyze, plan, etc.)\n\n---\n\n## Installation & Configuration\n\n### Quick Start\n\nAdd to your Claude Code workspace `.mcp.json`:\n\n**Option 1: Using npx (Recommended after package is published)**\n\n```json\n{\n  \"mcpServers\": {\n    \"spec-kit-adapter\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@code3-team/spec-kit-mcp-adapter\"],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"ghp_your_token_here\",\n        \"GITHUB_REPO\": \"owner/repo\",\n        \"ETHEREUM_PRIVATE_KEY\": \"0x_your_ethereum_key_here\",\n        \"APTOS_PRIVATE_KEY\": \"0x_your_aptos_key_here\"\n      }\n    }\n  }\n}\n```\n\n**Option 2: Using local path (For development)**\n\n```json\n{\n  \"mcpServers\": {\n    \"spec-kit-adapter\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/Code3/task3/adapters/spec-kit-mcp-adapter/dist/server.js\"],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"ghp_your_token_here\",\n        \"GITHUB_REPO\": \"owner/repo\",\n        \"ETHEREUM_PRIVATE_KEY\": \"0x_your_ethereum_key_here\",\n        \"APTOS_PRIVATE_KEY\": \"0x_your_aptos_key_here\"\n      }\n    }\n  }\n}\n```\n\n**That's it!** System configurations (RPC URLs, Contract Addresses) are managed in `src/chain-config.ts`.\n\n### Configuration Layers\n\n#### 1. **User Configuration** (`.mcp.json` in your workspace)\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `GITHUB_TOKEN` | ✅ Yes | GitHub Personal Access Token with `repo` scope |\n| `GITHUB_REPO` | ✅ Yes | Repository in format `owner/repo` |\n| `ETHEREUM_PRIVATE_KEY` | ⚠️ Choose one | Ethereum account private key (for Sepolia testnet) |\n| `APTOS_PRIVATE_KEY` | ⚠️ Choose one | Aptos account private key (for Aptos testnet) |\n| `LOCAL_SPECS_DIR` | ❌ No | Local directory for specs (default: `./specs`) |\n\n**Notes**:\n- You need **at least one** blockchain private key (Ethereum or Aptos)\n- For Ethereum: Get testnet ETH from [Sepolia Faucet](https://sepoliafaucet.com/)\n- For Aptos: Get testnet APT from [Aptos Faucet](https://aptoslabs.com/testnet-faucet)\n\n#### 2. **System Configuration** (`src/chain-config.ts`)\n\nManaged by Code3 team, you **don't need to configure** these:\n\n**Ethereum Sepolia**:\n- RPC URL: `https://ethereum-sepolia-rpc.publicnode.com`\n- Contract Address: `0x28FE83352f2451c54d9050761DF1d7F8945a8fc4`\n\n**Aptos Testnet**:\n- RPC URL: `https://fullnode.testnet.aptoslabs.com/v1`\n- Module Address: `0x28a6173...` (auto-configured)\n\n**Why this separation?**\n- Users only configure **credentials** (tokens, keys, repo)\n- System configs (RPC URLs, contract addresses) are **version-controlled** and updated by Code3 team\n- Reduces configuration errors and simplifies setup\n\n---\n\n## Project Structure\n\n```\nspec-kit-mcp-adapter/\n├── src/\n│   ├── chain-config.ts       # System-level blockchain configs (RPC, contracts)\n│   ├── data-operator.ts      # SpecKitDataOperator (GitHub operations)\n│   ├── tools/                # 6 Bounty flow tools\n│   │   ├── guide.ts          # Get started guide for Users/Workers\n│   │   ├── publish-bounty.ts # Publish bounty (spec.md → Issue → on-chain)\n│   │   ├── accept-bounty.ts  # Accept bounty (on-chain → download spec)\n│   │   ├── submit-bounty.ts  # Submit work (create PR → on-chain)\n│   │   ├── confirm-bounty.ts # Confirm work (User confirms submission)\n│   │   └── claim-bounty.ts   # Claim payout (after cooling period)\n│   ├── server.ts             # MCP server (exposes 6 tools)\n│   └── index.ts              # Package exports\n├── tests/                    # Unit and E2E tests\n│   ├── e2e-ethereum-spec-kit.test.ts\n│   └── e2e-aptos-spec-kit.test.ts\n├── package.json\n└── .env.test.example         # Test environment template\n```\n\n---\n\n## Development\n\n### Build\n\n```bash\npnpm run build\n```\n\n### Run Tests\n\n**E2E Tests** require real credentials:\n\n```bash\n# 1. Copy test config template\ncp .env.test.example .env.test\n\n# 2. Fill in your test credentials (see .env.test.example for details)\n\n# 3. Run E2E tests\npnpm test:e2e\n```\n\n**What tests do**:\n- Create real GitHub Issues/PRs\n- Create real blockchain transactions on testnets\n- Require manual cleanup after tests\n\n### Start MCP Server Locally\n\n```bash\n# After build\nnode dist/server.js\n\n# Or using pnpm script\npnpm start\n```\n\n---\n\n## Available Tools\n\n### 1. guide\n\nGet started guide for Users and Workers.\n\n**Parameters**:\n- `role`: `user` or `worker`\n\n**Example**:\n```typescript\n{\n  \"role\": \"user\"\n}\n```\n\n---\n\n### 2. publish-bounty\n\nPublish a bounty to GitHub Issue and blockchain.\n\n**Parameters**:\n- `specPath`: Local spec.md file path (e.g., `specs/001/spec.md`)\n- `repo`: GitHub repository (format: `owner/repo`)\n- `amount`: Bounty amount in smallest unit\n  - Ethereum: `\"10000000000000000\"` (0.01 ETH)\n  - Aptos: `\"100000000\"` (1 APT)\n- `asset`: Asset symbol (`ETH` or `APT`)\n- `chain`: Target blockchain (`ethereum` or `aptos`, default: `ethereum`)\n\n**Example**:\n```typescript\n{\n  \"specPath\": \"specs/001/spec.md\",\n  \"repo\": \"code3-team/bounty-repo\",\n  \"amount\": \"10000000000000000\",\n  \"asset\": \"ETH\",\n  \"chain\": \"ethereum\"\n}\n```\n\n**Returns**:\n- Issue URL\n- Bounty ID\n- Transaction hash\n- Chain and contract address\n\n---\n\n### 3. accept-bounty\n\nAccept a bounty and download spec.md to local.\n\n**Parameters**:\n- `issueUrl`: GitHub Issue URL\n- `chain`: Target blockchain (`ethereum` or `aptos`, default: `ethereum`)\n\n**Example**:\n```typescript\n{\n  \"issueUrl\": \"https://github.com/owner/repo/issues/123\",\n  \"chain\": \"ethereum\"\n}\n```\n\n**Returns**:\n- Bounty ID\n- Local path where spec.md was saved\n- Transaction hash\n\n---\n\n### 4. submit-bounty\n\nSubmit work via Pull Request.\n\n**Parameters**:\n- `issueUrl`: GitHub Issue URL\n- `branchName`: Git branch with changes\n- `summary`: PR summary (optional)\n- `filesChanged`: List of changed files (optional)\n- `testing`: Testing notes (optional)\n- `chain`: Target blockchain (`ethereum` or `aptos`, default: `ethereum`)\n\n**Example**:\n```typescript\n{\n  \"issueUrl\": \"https://github.com/owner/repo/issues/123\",\n  \"branchName\": \"feat/implement-spec-123\",\n  \"summary\": \"Implemented user authentication feature\",\n  \"chain\": \"ethereum\"\n}\n```\n\n**Returns**:\n- PR URL\n- Transaction hash\n\n---\n\n### 5. confirm-bounty\n\nConfirm a submitted PR (User role).\n\n**Parameters**:\n- `issueUrl`: GitHub Issue URL\n- `chain`: Target blockchain (`ethereum` or `aptos`, default: `ethereum`)\n\n**Example**:\n```typescript\n{\n  \"issueUrl\": \"https://github.com/owner/repo/issues/123\",\n  \"chain\": \"ethereum\"\n}\n```\n\n**Returns**:\n- Transaction hash\n- Confirmed timestamp\n- Cooling period end time (if applicable)\n\n**Note**:\n- Ethereum has no cooling period (can claim immediately after confirm)\n- Aptos may have a cooling period (check contract configuration)\n\n---\n\n### 6. claim-bounty\n\nClaim payout after confirmation (Worker role).\n\n**Parameters**:\n- `issueUrl`: GitHub Issue URL\n- `chain`: Target blockchain (`ethereum` or `aptos`, default: `ethereum`)\n\n**Example**:\n```typescript\n{\n  \"issueUrl\": \"https://github.com/owner/repo/issues/123\",\n  \"chain\": \"ethereum\"\n}\n```\n\n**Returns**:\n- Amount paid\n- Transaction hash\n\n---\n\n## Testing\n\n### E2E Test Configuration\n\nFor E2E tests, copy `.env.test.example` to `.env.test`:\n\n```bash\n# GitHub credentials\nGITHUB_TOKEN=ghp_your_test_token_here\nTEST_REPO=your-username/code3-e2e-test\n\n# Choose one or both chains to test\nETHEREUM_PRIVATE_KEY=0x_your_ethereum_test_key_here\nAPTOS_PRIVATE_KEY=0x_your_aptos_test_key_here\n```\n\n**Notes**:\n- System configs (RPC URLs, contract addresses) are automatically loaded from `src/chain-config.ts`\n- Tests create real resources (Issues, PRs, transactions)\n- Manual cleanup required after tests\n\n---\n\n## System Configuration Updates\n\nIf you're a Code3 team member updating blockchain configurations:\n\n**Edit `src/chain-config.ts`**:\n\n```typescript\nexport const ETHEREUM_CONFIGS: Record<string, ChainConfig> = {\n  sepolia: {\n    rpcUrl: 'https://ethereum-sepolia-rpc.publicnode.com',\n    contractAddress: '0x28FE83352f2451c54d9050761DF1d7F8945a8fc4', // Update here\n    network: 'sepolia'\n  }\n};\n\nexport const APTOS_CONFIGS: Record<string, ChainConfig> = {\n  testnet: {\n    rpcUrl: 'https://fullnode.testnet.aptoslabs.com/v1',\n    contractAddress: '0x28a61734...', // Update here\n    network: 'testnet'\n  }\n};\n```\n\nAfter updating:\n1. Rebuild: `pnpm run build`\n2. Commit changes\n3. Users get new configs on next restart (no manual config needed!)\n\n---\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-0a386b2f8d9add311d73e04ab0adc68c"}