{"id":47622482,"url":"https://github.com/fjpulidop/specrails-mcp","last_synced_at":"2026-04-01T22:23:05.319Z","repository":{"id":346027295,"uuid":"1188051524","full_name":"fjpulidop/specrails-mcp","owner":"fjpulidop","description":"MCP server exposing specrails-core knowledge to Claude, Cursor, and other MCP clients","archived":false,"fork":false,"pushed_at":"2026-03-21T22:44:04.000Z","size":184,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-22T11:04:23.267Z","etag":null,"topics":["claude","mcp","model-context-protocol","openspec","specrails","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/specrails-mcp","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fjpulidop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-21T14:54:22.000Z","updated_at":"2026-03-21T22:44:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fjpulidop/specrails-mcp","commit_stats":null,"previous_names":["fjpulidop/specrails-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fjpulidop/specrails-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fjpulidop%2Fspecrails-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fjpulidop%2Fspecrails-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fjpulidop%2Fspecrails-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fjpulidop%2Fspecrails-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fjpulidop","download_url":"https://codeload.github.com/fjpulidop/specrails-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fjpulidop%2Fspecrails-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","mcp","model-context-protocol","openspec","specrails","typescript"],"created_at":"2026-04-01T22:23:03.421Z","updated_at":"2026-04-01T22:23:05.304Z","avatar_url":"https://github.com/fjpulidop.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# specrails-mcp\n\nMCP server that gives AI assistants full access to your [specrails](https://github.com/fjpulidop/specrails-mcp) projects — specs, personas, memory, jobs, analytics, and more.\n\nWorks with any MCP-compatible client: Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI, and others.\n\n```\nnpm install -g specrails-mcp\n```\n\n---\n\n## Quick start\n\n### 1. Add to your MCP client\n\n**Claude Code** (`~/.claude/settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"specrails\": {\n      \"command\": \"specrails-mcp\",\n      \"args\": [],\n      \"env\": {\n        \"SPECRAILS_PROJECT_ROOT\": \"/path/to/your/project\"\n      }\n    }\n  }\n}\n```\n\n**Claude Desktop** (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"specrails\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"specrails-mcp\"],\n      \"env\": {\n        \"SPECRAILS_PROJECT_ROOT\": \"/path/to/your/project\"\n      }\n    }\n  }\n}\n```\n\n### 2. Talk to your AI assistant\n\n```\nYou: \"What projects do I have in specrails?\"\nAI:  → calls list_projects → shows your registered projects\n\nYou: \"Run a health-check on DeckDex\"\nAI:  → calls enqueue_job with command \"health-check\" → job starts\n\nYou: \"How much have I spent in the last 7 days?\"\nAI:  → calls get_analytics with period \"7d\" → shows cost breakdown\n```\n\nThat's it. The AI discovers available tools and resources automatically via MCP.\n\n---\n\n## Tools\n\nEight tools your AI assistant can call:\n\n### Core\n\n| Tool         | Description                                                                                          |\n| ------------ | ---------------------------------------------------------------------------------------------------- |\n| **`doctor`** | Health check of your specrails installation. Verifies directories, config files, and provider setup. |\n\n### Hub — Query\n\n| Tool                 | Description                                                                                                                |\n| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |\n| **`hub_status`**     | Is the hub server running? How many projects are registered?                                                               |\n| **`list_projects`**  | List all projects registered in specrails-hub.                                                                             |\n| **`get_project`**    | Get details for a specific project (path, provider, timestamps).                                                           |\n| **`get_jobs`**       | List jobs for a project. Filter by status (`running`, `success`, `failed`, `cancelled`). Supports pagination.              |\n| **`get_job_detail`** | Full detail for a specific job — phases, event log, tokens, cost, exit code.                                               |\n| **`get_analytics`**  | Cost, job counts, success rates, token usage. Scope to a project or get hub-wide aggregation. Periods: `7d`, `30d`, `all`. |\n\n### Hub — Action\n\n| Tool              | Description                                                                                      |\n| ----------------- | ------------------------------------------------------------------------------------------------ |\n| **`enqueue_job`** | Queue a new AI job in a project. Requires the hub server to be running. Supports model override. |\n\n#### `enqueue_job` parameters\n\n| Parameter   | Required | Description                                       |\n| ----------- | -------- | ------------------------------------------------- |\n| `projectId` | Yes      | Project ID (get it from `list_projects`)          |\n| `command`   | Yes      | Command to run (see below)                        |\n| `model`     | No       | Override the AI model (e.g., `\"claude-opus-4-6\"`) |\n\n#### Known commands\n\n| Command                         | What it does                                                  |\n| ------------------------------- | ------------------------------------------------------------- |\n| `implement`                     | Implement a specific ticket (e.g., `\"implement #42\"`)         |\n| `health-check`                  | Audit the health of a project                                 |\n| `product-backlog`               | Generate/update GitHub Issues for a project's product backlog |\n| `update-product-driven-backlog` | Refresh the product-driven backlog                            |\n\n---\n\n## Resources\n\nRead-only data your AI assistant can access via MCP resource URIs.\n\n### Project resources (specrails-core)\n\nRead from the local project directory:\n\n| URI                               | Description                                                        |\n| --------------------------------- | ------------------------------------------------------------------ |\n| `specrails://specs/{name}`        | OpenSpec specification files (YAML, JSON, Markdown)                |\n| `specrails://changes/{name}`      | OpenSpec change records                                            |\n| `specrails://config/openspec`     | Project configuration (`openspec/config.yaml`)                     |\n| `specrails://config/instructions` | Agent instructions file (`CLAUDE.md` or `CODEX.md`, auto-detected) |\n| `specrails://personas/{name}`     | VPC persona definitions                                            |\n| `specrails://memory/{name}`       | Agent memory files                                                 |\n| `specrails://skills/{name}`       | Skill definitions (`SKILL.md`)                                     |\n| `specrails://provider`            | Active CLI provider info (claude or codex)                         |\n\n### Hub resources (specrails-hub)\n\nRead from the `~/.specrails` SQLite databases:\n\n| URI                                                 | Description                                         |\n| --------------------------------------------------- | --------------------------------------------------- |\n| `specrails://hub/projects`                          | All registered projects with metadata               |\n| `specrails://hub/projects/{projectId}`              | Single project detail with quick stats              |\n| `specrails://hub/projects/{projectId}/jobs`         | Recent jobs (last 50) with status, cost, duration   |\n| `specrails://hub/projects/{projectId}/jobs/{jobId}` | Full job detail with event log                      |\n| `specrails://hub/analytics`                         | Hub-wide analytics (last 30 days)                   |\n| `specrails://hub/projects/{projectId}/analytics`    | Project-specific analytics with daily cost timeline |\n\n---\n\n## Typical workflow\n\n```\nhub_status → list_projects → enqueue_job → get_jobs → get_job_detail\n   ↓              ↓              ↓             ↓              ↓\n\"Is it up?\"  \"What's there?\"  \"Launch it\"  \"How's it going?\"  \"What happened?\"\n```\n\n### Check system health\n\n```\n\"Run the specrails doctor\"        → doctor\n\"Is the hub running?\"             → hub_status\n```\n\n### Discover and inspect projects\n\n```\n\"What projects do I have?\"        → list_projects\n\"Show me details for DeckDex\"     → get_project\n```\n\n### Run and monitor jobs\n\n```\n\"Implement ticket #42 on DeckDex\"              → enqueue_job (command: \"implement #42\")\n\"Run a health-check on mechboards\"             → enqueue_job (command: \"health-check\")\n\"Launch product-backlog on DeckDex with opus\"   → enqueue_job (model: \"claude-opus-4-6\")\n\"What jobs are running right now?\"              → get_jobs (status: \"running\")\n\"Show me the last 5 failed jobs\"               → get_jobs (status: \"failed\", limit: 5)\n\"Why did job f496a1b0 fail?\"                   → get_job_detail\n```\n\n### Track costs and performance\n\n```\n\"How much has DeckDex cost this week?\"         → get_analytics (period: \"7d\")\n\"Show me analytics for all projects\"           → get_analytics (no projectId)\n\"What's the success rate for specrails-core?\"  → get_analytics\n\"Which project spent the most this month?\"     → get_analytics (period: \"30d\")\n```\n\n---\n\n## Architecture\n\n```\n┌─────────────────────┐     stdio      ┌──────────────────────────┐\n│   MCP Client        │◄──────────────►│   specrails-mcp          │\n│                     │                │                          │\n│   Claude Code       │                │   Resources (read-only)  │\n│   Claude Desktop    │                │   ├── openspec/          │\n│   Cursor            │                │   ├── .claude/ (.codex/) │\n│   Windsurf          │                │   └── ~/.specrails DBs   │\n│   Codex CLI         │                │                          │\n│   ...               │                │   Tools (read + action)  │\n│                     │                │   ├── doctor             │\n└─────────────────────┘                │   ├── hub queries        │\n                                       │   └── enqueue_job → Hub  │\n                                       └──────────────────────────┘\n```\n\n- **Transport**: stdio (JSON-RPC over stdin/stdout)\n- **Resources**: Read-only. Project files + hub SQLite databases.\n- **Tools**: Read queries are always safe. `enqueue_job` creates jobs via the hub HTTP API.\n- **Provider-aware**: Auto-detects Claude or Codex CLI and reads from the correct config directory.\n- **No filesystem writes**: All resource access is strictly read-only with path traversal prevention.\n\n---\n\n## Environment variables\n\n| Variable                 | Default                   | Description                             |\n| ------------------------ | ------------------------- | --------------------------------------- |\n| `SPECRAILS_PROJECT_ROOT` | Current working directory | Root directory of the specrails project |\n\n\u003e Hub tools connect to `http://localhost:4200` (the default specrails-hub address).\n\n---\n\n## Prerequisites\n\n- **Node.js** \u003e= 20\n- **specrails-core** initialized in your project (`openspec/` directory)\n- **specrails-hub** running locally (required only for hub tools: `hub_status`, `enqueue_job`, etc.)\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/fjpulidop/specrails-mcp.git\ncd specrails-mcp\nnpm install\nnpm run build\n```\n\n| Command                 | Description         |\n| ----------------------- | ------------------- |\n| `npm run dev`           | Watch mode with tsx |\n| `npm test`              | Run tests (Vitest)  |\n| `npm run test:coverage` | Coverage report     |\n| `npm run lint`          | ESLint              |\n| `npm run typecheck`     | TypeScript check    |\n| `npm run build`         | Production build    |\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffjpulidop%2Fspecrails-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffjpulidop%2Fspecrails-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffjpulidop%2Fspecrails-mcp/lists"}