@arimakouyou/spec-workflow-mcp 2.2.7

package/README.md

@@ -0,0 +1,437 @@
+# Spec Workflow MCP
+
+[![npm version](https://img.shields.io/npm/v/@arimakouyou/spec-workflow-mcp)](https://www.npmjs.com/package/@arimakouyou/spec-workflow-mcp)
+[![VSCode Extension](https://vsmarketplacebadges.dev/version-short/arimakouyou.spec-workflow-mcp.svg)](https://marketplace.visualstudio.com/items?itemName=arimakouyou.spec-workflow-mcp)
+
+A Model Context Protocol (MCP) server for structured spec-driven development with real-time dashboard and VSCode extension.
+
+## ☕ Support This Project
+
+<a href="https://buymeacoffee.com/arimakouyou" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
+
+## 📺 Showcase
+
+### 🔄 Approval System in Action
+<a href="https://www.youtube.com/watch?v=C-uEa3mfxd0" target="_blank">
+  <img src="https://img.youtube.com/vi/C-uEa3mfxd0/maxresdefault.jpg" alt="Approval System Demo" width="600">
+</a>
+
+*See how the approval system works: create documents, request approval through the dashboard, provide feedback, and track revisions.*
+
+### 📊 Dashboard & Spec Management
+<a href="https://www.youtube.com/watch?v=g9qfvjLUWf8" target="_blank">
+  <img src="https://img.youtube.com/vi/g9qfvjLUWf8/maxresdefault.jpg" alt="Dashboard Demo" width="600">
+</a>
+
+*Explore the real-time dashboard: view specs, track progress, navigate documents, and monitor your development workflow.*
+
+## ✨ Key Features
+
+- **Structured Development Workflow** - Sequential spec creation (Requirements → Design → Test Design → Tasks)
+- **Real-Time Web Dashboard** - Monitor specs, tasks, and progress with live updates
+- **VSCode Extension** - Integrated sidebar dashboard for VSCode users
+- **Approval Workflow** - Complete approval process with revisions
+- **Task Progress Tracking** - Visual progress bars and detailed status
+- **Implementation Logs** - Searchable logs of all task implementations with code statistics
+- **Multi-Language Support** - Available in 11 languages
+
+## 🌍 Supported Languages
+
+🇺🇸 English • 🇯🇵 日本語 • 🇨🇳 中文 • 🇪🇸 Español • 🇧🇷 Português • 🇩🇪 Deutsch • 🇫🇷 Français • 🇷🇺 Русский • 🇮🇹 Italiano • 🇰🇷 한국어 • 🇸🇦 العربية
+
+**📖 Documentation in your language:**
+
+[English](README.md) | [日本語](README.ja.md) | [中文](README.zh.md) | [Español](README.es.md) | [Português](README.pt.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Русский](README.ru.md) | [Italiano](README.it.md) | [한국어](README.ko.md) | [العربية](README.ar.md)
+
+## 🚀 Quick Start
+
+### Option 1: Claude Code Plugin (Recommended for Claude Code users)
+
+Install directly as a Claude Code plugin — skills, agents, rules, hooks, and MCP server are all configured automatically:
+
+```bash
+claude plugin add --from https://github.com/arimakouyou/spec-workflow-mcp
+```
+
+Two plugin variants are available:
+
+| Plugin | Description |
+|--------|-------------|
+| `spec-workflow-mcp` | MCP server + skills/agents/rules/hooks |
+| `spec-workflow-mcp-with-dashboard` | MCP server only (lightweight, no skills/agents/rules/hooks) |
+
+> **Note**: The `spec-workflow-mcp-with-dashboard` variant is a minimal configuration containing only the MCP server. To use the dashboard, start it separately with `npx -y @arimakouyou/spec-workflow-mcp@latest --dashboard`.
+
+> **What the plugin includes:**
+> - MCP server for spec-driven development workflow
+> - Skills: spec-requirements, spec-design, spec-test-design, spec-tasks, spec-implement, spec-review, integration-test, TDD, and more
+> - Agents: code-simplifier, review-worker, unit-test-engineer, parallel-worker, etc.
+> - Rules: project architecture, quality checks, security, design principles, etc.
+> - Hooks: automated task read guards
+
+### Option 2: Manual MCP Configuration
+
+Add to your MCP configuration (see client-specific setup below):
+
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+### Step 2: Choose your interface
+
+**Option A: Web Dashboard** (Required for CLI users)
+Start the dashboard (runs on port 5000 by default):
+```bash
+npx -y @arimakouyou/spec-workflow-mcp@latest --dashboard
+```
+
+The dashboard will be accessible at: http://localhost:5000
+
+> **Note:** Only one dashboard instance is needed. All your projects will connect to the same dashboard.
+
+**Option B: VSCode Extension** (Recommended for VSCode users)
+
+Install [Spec Workflow MCP Extension](https://marketplace.visualstudio.com/items?itemName=arimakouyou.spec-workflow-mcp) from the VSCode marketplace.
+
+## 📝 How to Use
+
+Simply mention spec-workflow in your conversation:
+
+- **"Create a spec for user authentication"** - Creates complete spec workflow
+- **"List my specs"** - Shows all specs and their status
+- **"Execute task 1.2 in spec user-auth"** - Runs a specific task
+
+[See more examples →](docs/PROMPTING-GUIDE.md)
+
+## 🔧 MCP Client Setup
+
+<details>
+<summary><strong>Augment Code</strong></summary>
+
+Configure in your Augment settings:
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Claude Code CLI</strong></summary>
+
+Add to your MCP configuration:
+```bash
+claude mcp add spec-workflow npx @arimakouyou/spec-workflow-mcp@latest -- /path/to/your/project
+```
+
+**Important Notes:**
+- The `-y` flag bypasses npm prompts for smoother installation
+- The `--` separator ensures the path is passed to the spec-workflow script, not to npx
+- Replace `/path/to/your/project` with your actual project directory path
+
+**Alternative for Windows (if the above doesn't work):**
+```bash
+claude mcp add spec-workflow cmd.exe /c "npx @arimakouyou/spec-workflow-mcp@latest /path/to/your/project"
+```
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+> **Important:** Run the dashboard separately with `--dashboard` before starting the MCP server.
+
+</details>
+
+<details>
+<summary><strong>Cline/Claude Dev</strong></summary>
+
+Add to your MCP server configuration:
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Continue IDE Extension</strong></summary>
+
+Add to your Continue configuration:
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Cursor IDE</strong></summary>
+
+Add to your Cursor settings (`settings.json`):
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>OpenCode</strong></summary>
+
+Add to your `opencode.json` configuration file:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "spec-workflow": {
+      "type": "local",
+      "command": ["npx", "-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"],
+      "enabled": true
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+Add to your `~/.codeium/windsurf/mcp_config.json` configuration file:
+```json
+{
+  "mcpServers": {
+    "spec-workflow": {
+      "command": "npx",
+      "args": ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><strong>Codex</strong></summary>
+
+Add to your `~/.codex/config.toml` configuration file:
+```toml
+[mcp_servers.spec-workflow]
+command = "npx"
+args = ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
+```
+</details>
+
+## 🐳 Docker Deployment
+
+Run the dashboard in a Docker container for isolated deployment:
+
+```bash
+# Using Docker Compose (recommended)
+cd containers
+docker-compose up --build
+
+# Or using Docker CLI
+docker build -f containers/Dockerfile -t spec-workflow-mcp .
+docker run -p 5000:5000 -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" spec-workflow-mcp
+```
+
+The dashboard will be available at: http://localhost:5000
+
+[See Docker setup guide →](containers/README.md)
+
+## 🔒 Security
+
+Spec-Workflow MCP includes enterprise-grade security features suitable for corporate environments:
+
+### ✅ Implemented Security Controls
+
+| Feature | Description |
+|---------|-------------|
+| **Localhost Binding** | Binds to `127.0.0.1` by default, preventing network exposure |
+| **Rate Limiting** | 120 requests/minute per client with automatic cleanup |
+| **Audit Logging** | Structured JSON logs with timestamp, actor, action, and result |
+| **Security Headers** | X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, CSP, Referrer-Policy |
+| **CORS Protection** | Restricted to localhost origins by default |
+| **Docker Hardening** | Non-root user, read-only filesystem, dropped capabilities, resource limits |
+
+### ⚠️ Not Yet Implemented
+
+| Feature | Workaround |
+|---------|------------|
+| **HTTPS/TLS** | Use a reverse proxy (nginx, Apache) with TLS certificates |
+| **User Authentication** | Use a reverse proxy with Basic Auth or OAuth2 Proxy for SSO |
+
+### For External/Network Access
+
+If you need to expose the dashboard beyond localhost, we recommend:
+
+1. **Keep dashboard on localhost** (`127.0.0.1`)
+2. **Use nginx or Apache** as a reverse proxy with:
+   - TLS/HTTPS termination
+   - Basic authentication or OAuth2
+3. **Configure firewall rules** to restrict access
+
+```nginx
+# Example nginx reverse proxy with auth
+server {
+    listen 443 ssl;
+    server_name dashboard.example.com;
+    
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+    
+    auth_basic "Dashboard Access";
+    auth_basic_user_file /etc/nginx/.htpasswd;
+    
+    location / {
+        proxy_pass http://127.0.0.1:5000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+[See Docker security guide →](containers/README.md#security-configuration)
+
+## 🔒 Sandboxed Environments
+
+For sandboxed environments (e.g., Codex CLI with `sandbox_mode=workspace-write`) where `$HOME` is read-only, use the `SPEC_WORKFLOW_HOME` environment variable to redirect global state files to a writable location:
+
+```bash
+SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @arimakouyou/spec-workflow-mcp@latest /workspace
+```
+
+[See Configuration Guide →](docs/CONFIGURATION.md#environment-variables)
+
+## 📚 Documentation
+
+- [Configuration Guide](docs/CONFIGURATION.md) - Command-line options, config files
+- [User Guide](docs/USER-GUIDE.md) - Comprehensive usage examples
+- [Workflow Process](docs/WORKFLOW.md) - Development workflow and best practices
+- [Interfaces Guide](docs/INTERFACES.md) - Dashboard and VSCode extension details
+- [Prompting Guide](docs/PROMPTING-GUIDE.md) - Advanced prompting examples
+- [Tools Reference](docs/TOOLS-REFERENCE.md) - Complete tools documentation
+- [Development](docs/DEVELOPMENT.md) - Contributing and development setup
+- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions
+
+## 📁 Project Structure
+
+### Working Directory (per project)
+
+```
+your-project/
+  .spec-workflow/
+    approvals/
+    archive/
+    specs/
+    steering/
+    templates/
+    user-templates/
+    config.example.toml
+```
+
+### Plugin Structure (distributed via `.claude-plugin/`)
+
+```
+.claude-plugin/
+  plugin.json              # Plugin manifest
+  marketplace.json         # Marketplace listing
+  .mcp.json                # MCP server configuration
+  hooks/
+    hooks.json             # Hook definitions (PostToolUse, etc.)
+    tasks-read-guard.sh    # Task read guard script
+  skills/                  # Spec-driven workflow skills
+    spec-requirements/     # Requirements creation
+    spec-design/           # Design document creation
+    spec-test-design/      # Test design creation
+    spec-tasks/            # Task breakdown
+    spec-implement/        # Implementation workflow
+    spec-review/           # Code review
+    integration-test/      # Integration testing
+    tdd-skills/            # TDD workflow
+    tdd-skills-rust/       # Rust-specific TDD
+    knowhow-capture/       # Knowledge capture
+  agents/                  # Specialized sub-agents
+    code-simplifier.md     # Code simplification
+    review-worker.md       # Review automation
+    unit-test-engineer.md  # Unit test generation
+    parallel-worker.md     # Parallel task execution
+    integ-test-worker.md   # Integration test worker
+    integ-test-auditor.md  # Integration test auditor
+  rules/                   # Project rules and conventions
+    quality-checks.md      # Quality enforcement
+    security.md            # Security guidelines
+    design-principles.md   # Design principles
+    ...
+  with-dashboard/          # Dashboard variant plugin
+    plugin.json
+    .mcp.json
+```
+
+## 🛠️ Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run in development mode
+npm run dev
+```
+
+[See development guide →](docs/DEVELOPMENT.md)
+
+## 📄 License
+
+GPL-3.0
+
+## ⭐ Star History
+
+<a href="https://www.star-history.com/#arimakouyou/spec-workflow-mcp&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=arimakouyou/spec-workflow-mcp&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=arimakouyou/spec-workflow-mcp&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=arimakouyou/spec-workflow-mcp&type=Date" />
+ </picture>
+</a>

package/dist/__tests__/config.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config.test.d.ts.map

package/dist/__tests__/config.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/config.test.ts"],"names":[],"mappings":""}