{
  "markdown": "# StackGuide MCP Server\n\nDynamic context + active engineering workflow for AI coding assistants in Cursor, VS Code, and other MCP clients.\n\n[![npm version](https://img.shields.io/npm/v/@stackguide/mcp-server.svg)](https://www.npmjs.com/package/@stackguide/mcp-server)\n[![license](https://img.shields.io/badge/license-GPL--3.0-green.svg)](./LICENSE)\n[![mcp registry](https://img.shields.io/badge/MCP%20Registry-io.github.isucorp--taimiralain%2Fstackguide--mcp-blue)](https://registry.modelcontextprotocol.io)\n\n## What It Does\n\n`@stackguide/mcp-server` helps teams standardize implementation quality with:\n\n- project-aware rule/context loading\n- code review and health scoring\n- auto-detected setup and stack scaffolding\n- active agent workflow that executes real work (`intake`, `plan`, `verify`, `release`)\n- adaptive TDD preferences per project (model + token profile)\n- Jira ticket creation from strict `MAIN DESCRIPTION` templates\n- tracker + VCS + test orchestration for delivery flow\n\nThis server is built for real team usage, not just prompt templates.\n\n## What's New In v4.x\n\n- Added active `agent` tool (execution-first workflow).\n- `init` now generates `.stackguide/config.json` automatically.\n- Added tracker service support for GitHub, GitLab, and Jira.\n- Added VCS service for branch checks, commit parsing, CI status, and PR/MR creation.\n- Added test runner service for structured `test`/`lint`/`build` execution.\n- Updated TDD prompts to use active tool calls instead of large passive markdown payloads.\n- Hardened local persistence:\n  - `.stackguide` artifacts removed from version control\n  - repository guard blocks accidental tracking of local artifacts\n  - cache and health history include integrity validation and safer writes\n\n## Install By IDE\n\n### Cursor\n\n- File (workspace): `.cursor/mcp.json`\n- File (global): `~/.cursor/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"stackguide\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@stackguide/mcp-server@latest\"]\n    }\n  }\n}\n```\n\n### JetBrains (IntelliJ, WebStorm, PhpStorm, etc.)\n\n- Open `Settings | Tools | AI Assistant | Model Context Protocol (MCP)`.\n- Click **Add** and paste JSON config.\n- Recommended: set it as **Project-level** unless you want global scope.\n\n```json\n{\n  \"mcpServers\": {\n    \"stackguide\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@stackguide/mcp-server@latest\"]\n    }\n  }\n}\n```\n\n### VS Code\n\n- Requirement: GitHub Copilot Chat with MCP enabled.\n- File (workspace): `.vscode/mcp.json`\n- VS Code MCP schema uses `servers` as root key.\n\n```json\n{\n  \"servers\": {\n    \"stackguide\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@stackguide/mcp-server@latest\"]\n    }\n  }\n}\n```\n\n### Visual Studio (Windows, 2022 17.14+ / 2026+)\n\n- Enable GitHub Copilot Agent mode.\n- Supported config locations include:\n  - `%USERPROFILE%\\\\.mcp.json` (global)\n  - `<solution>\\\\.mcp.json` (repo-scoped)\n  - `<solution>\\\\.vs\\\\mcp.json` (solution/user-scoped)\n- Visual Studio MCP schema uses `servers` as root key.\n\n```json\n{\n  \"servers\": {\n    \"stackguide\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@stackguide/mcp-server@latest\"]\n    }\n  }\n}\n```\n\n## How To Use (Any IDE)\n\n1. Restart the IDE after adding the MCP configuration.\n2. Open AI chat in agent/tool mode.\n3. Call `setup` to detect project context.\n4. Call `init action:\"full\"` to scaffold `.stackguide/` and defaults.\n5. Use `agent` actions (`intake`, `create_ticket`, `plan`, `verify`, `release`) for delivery flow.\n\n## Quick Start\n\n1. Configure your project:\n\n```bash\nsetup type:\"react-typescript\" enableAdaptiveTdd:true model:\"gpt-5\" integrations:[\"jira\",\"github\"] tokenMode:\"compact\"\ninit action:\"full\" model:\"gpt-5\" tokenMode:\"compact\" integrations:[\"jira\",\"github\"] mcpSyncTargets:[\"cursor\",\"root\"] applyMcpTemplates:true\n```\n\n1. Check generated setup:\n\n```bash\ninit action:\"status\"\nagent action:\"status\"\n```\n\n1. Run active TDD workflow:\n\n```bash\nagent action:\"intake\" ticket:\"PROJ-123\"\nagent action:\"create_ticket\" mainDescription:\"<MAIN DESCRIPTION>\" projectKey:\"PROJ\"\nagent action:\"plan\" brief:\"<brief-from-intake>\"\nagent action:\"verify\"\nagent action:\"release\" version:\"v1.2.0\"\n```\n\n## Tools (16)\n\n### Core\n\n- `setup`: configure StackGuide context for project type\n- `context`: show currently loaded context\n- `rules`: list/search/get/select rule sets\n- `knowledge`: list/search/get knowledge files\n- `review`: analyze files/URLs/project code quality\n\n### Utility\n\n- `cursor`: browse/import community rules\n- `docs`: fetch/search/list documentation\n- `config`: save/load/export/import configurations\n- `custom_rule`: create/update/delete/list project custom rules\n- `help`: usage help by topic\n\n### Advanced\n\n- `generate`: boilerplate generation (component/hook/service/test/api/model/util)\n- `health`: project health score and recommendations\n- `analyze`: project intelligence (structure/config/dependency/generate/apply)\n\n### Workflow\n\n- `workflow`: lazy-load raw workflow assets (agents/skills/hooks/commands)\n- `init`: scaffold `.stackguide` with stack-aware defaults\n- `agent`: active workflow executor (`status`, `intake`, `create_ticket`, `plan`, `verify`, `release`)\n\n## Active Workflow Details\n\n### `agent action:\"intake\"`\n\n- reads ticket from configured tracker\n- returns normalized brief + gaps\n- proposes branch name convention\n- can optionally create a Jira ticket first (`createFromDescription:true`)\n\n### `agent action:\"create_ticket\"`\n\n- creates Jira issues using strict `MAIN DESCRIPTION` format\n- uses project defaults from `.stackguide/config.json` (`projectKey`, `issueType`)\n- derives `summary` from first line of `MAIN DESCRIPTION` when omitted\n\n### `agent action:\"plan\"`\n\n- inspects conventions + project shape\n- creates vertical-slice plan\n- returns exactly 3 target tests in structured format\n\n### `agent action:\"verify\"`\n\n- executes configured tests/lint/build per layer\n- checks branch naming + commit convention + TDD test budget\n- returns blocker list and final pass/fail report\n\n### `agent action:\"release\"`\n\n- checks CI status\n- parses commits since last tag\n- suggests semver impact (`major` / `minor` / `patch`)\n- can create tag and PR/MR (when enabled)\n\n## Local Data And Security\n\n`init` generates:\n\n- `.stackguide/config.json` (project workflow config)\n\nRuntime/local artifacts:\n\n- `.stackguide/analysis-cache.json`\n- `.stackguide/health-history.json`\n\nThese are machine-local and must not be committed.\n\n### Repository Guard\n\n`pnpm lint` includes:\n\n```bash\npnpm run guard:repo\n```\n\nThe guard fails if `.stackguide` artifacts are tracked.\n\n### Integrity Hardening\n\nCache/history persistence includes:\n\n- boundary/symlink checks\n- file size and entry limits\n- atomic write strategy\n- checksum validation\n- optional HMAC signature using:\n\n```bash\nSTACKGUIDE_INTEGRITY_KEY=<long-random-secret>\n```\n\nFor teams, configure `STACKGUIDE_INTEGRITY_KEY` in local/dev and CI environments for stronger tamper resistance.\n\n## Supported Stacks\n\n`python-django`, `python-fastapi`, `python-flask`, `react-node`, `react-typescript`, `vue-node`, `nextjs`, `express`, `nestjs`, `laravel`, `rails`, `golang`, `rust`, `custom`.\n\n## Development\n\nUse `pnpm` for all commands.\n\n```bash\npnpm install\npnpm lint\npnpm test\npnpm build\npnpm dev\n```\n\n## Release And Version Policy\n\n- Current secure baseline: `4.1.2+`\n- Versions from `3.0.0` up to `4.1.1` are deprecated in npm due to local artifact hygiene issues.\n- Use the latest `4.x` release in all environments.\n\n## Registry Identifiers\n\n- npm package: `@stackguide/mcp-server`\n- MCP Registry server: `io.github.isucorp-taimiralain/stackguide-mcp`\n\n## License\n\nGPL-3.0\n",
  "bytes": 7629,
  "sha": "9ae4518e129fea4f2055ef7f1a496d29c8dc07bd93ab53bfd50ece68092e4890",
  "repo_slug": "taimiralain/stackguide-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_taimiralain_stackguide_mcp_88f28ab5/readme"
}