stackguide-mcp

StackGuide MCP Server

Dynamic context + active engineering workflow for AI coding assistants in Cursor, VS Code, and other MCP clients.

What It Does

@stackguide/mcp-server helps teams standardize implementation quality with:

• project-aware rule/context loading
• code review and health scoring
• auto-detected setup and stack scaffolding
• active agent workflow that executes real work (intake, plan, verify, release)
• adaptive TDD preferences per project (model + token profile)
• Jira ticket creation from strict MAIN DESCRIPTION templates
• tracker + VCS + test orchestration for delivery flow

This server is built for real team usage, not just prompt templates.

What's New In v4.x

Full history: CHANGELOG.md.

• v4.3.1 - Update notifier: StackGuide checks npm once a day in the background and tells you once per session when a newer version exists, with a safe update command. Disable with STACKGUIDE_NO_UPDATE_CHECK=1.
• v4.3.0 - Team mode:
  • setup wizard:true asks stack, architecture, methodology, conventions and tracker, then writes a shared stackguide.config.json at the repo root. Commit it so every teammate gets the same context.
  • On startup StackGuide finds that file (also from subfolders) and loads it without running setup or re-detecting the project. context returns one guidance line per architecture and methodology.
  • Optional ruleCategories limits which rules are loaded (saves tokens). Existing healthWeights in the file are preserved.
  • Multi-agent roles that follow the IDE you are using (detected from the MCP client). Defaults: Claude Code opus / haiku / haiku; Cursor inherit (your selected model, e.g. Composer or Grok) / fast / fast; other IDEs inherit. The wizard asks which model each role should use (recommended default, your most used models first, or type any id your IDE lists); answer with models:{planner,implementer,verifier} or models:{} to accept the defaults. Choices are saved per IDE in stackguide.config.json, so mixed teams do not clash.
  • agent action:"plan" returns a delegation block for the current IDE, and the wizard writes stackguide-implementer.md / stackguide-verifier.md into .claude/agents/ and .cursor/agents/. Edited files are kept; only their model: line is refreshed.
  • Re-running setup wizard:true edits the saved config; .stackguide/ stays local and guarded.
• Added active agent tool (execution-first workflow).
• init now generates .stackguide/config.json automatically.
• Added tracker service support for GitHub, GitLab, and Jira.
• Added VCS service for branch checks, commit parsing, CI status, and PR/MR creation.
• Added test runner service for structured test/lint/build execution.
• Updated TDD prompts to use active tool calls instead of large passive markdown payloads.
• Hardened local persistence:
  • .stackguide artifacts removed from version control
  • repository guard blocks accidental tracking of local artifacts
  • cache and health history include integrity validation and safer writes

Install By IDE

Cursor

• File (workspace): .cursor/mcp.json
• File (global): ~/.cursor/mcp.json

{
  "mcpServers": {
    "stackguide": {
      "command": "npx",
      "args": ["-y", "@stackguide/mcp-server@latest"]
    }
  }
}

JetBrains (IntelliJ, WebStorm, PhpStorm, etc.)

• Open Settings | Tools | AI Assistant | Model Context Protocol (MCP).
• Click Add and paste JSON config.
• Recommended: set it as Project-level unless you want global scope.

{
  "mcpServers": {
    "stackguide": {
      "command": "npx",
      "args": ["-y", "@stackguide/mcp-server@latest"]
    }
  }
}

VS Code

• Requirement: GitHub Copilot Chat with MCP enabled.
• File (workspace): .vscode/mcp.json
• VS Code MCP schema uses servers as root key.

{
  "servers": {
    "stackguide": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stackguide/mcp-server@latest"]
    }
  }
}

Visual Studio (Windows, 2022 17.14+ / 2026+)

• Enable GitHub Copilot Agent mode.
• Supported config locations include:
  • %USERPROFILE%\\.mcp.json (global)
  • <solution>\\.mcp.json (repo-scoped)
  • <solution>\\.vs\\mcp.json (solution/user-scoped)
• Visual Studio MCP schema uses servers as root key.

{
  "servers": {
    "stackguide": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@stackguide/mcp-server@latest"]
    }
  }
}

How To Use (Any IDE)

1. Restart the IDE after adding the MCP configuration.
2. Open AI chat in agent/tool mode.
3. Call setup to detect project context.
4. Call init action:"full" to scaffold .stackguide/ and defaults.
5. Use agent actions (intake, create_ticket, plan, verify, release) for delivery flow.

Quick Start

Team setup (once per project, then commit stackguide.config.json):

setup wizard:true
setup wizard:true type:"nextjs" architecture:"clean" methodology:"tdd" conventions:["Use named exports"] tracker:"jira"

Personal setup:

1. Configure your project:

setup type:"react-typescript" enableAdaptiveTdd:true model:"gpt-5" integrations:["jira","github"] tokenMode:"compact"
init action:"full" model:"gpt-5" tokenMode:"compact" integrations:["jira","github"] mcpSyncTargets:["cursor","root"] applyMcpTemplates:true

1. Check generated setup:

init action:"status"
agent action:"status"

1. Run active TDD workflow:

agent action:"intake" ticket:"PROJ-123"
agent action:"create_ticket" mainDescription:"<MAIN DESCRIPTION>" projectKey:"PROJ"
agent action:"plan" brief:"<brief-from-intake>"
agent action:"verify"
agent action:"release" version:"v1.2.0"

Tools (16)

Core

• setup: configure StackGuide context for project type
• context: show currently loaded context
• rules: list/search/get/select rule sets
• knowledge: list/search/get knowledge files
• review: analyze files/URLs/project code quality

Utility

• cursor: browse/import community rules
• docs: fetch/search/list documentation
• config: save/load/export/import configurations
• custom_rule: create/update/delete/list project custom rules
• help: usage help by topic

Advanced

• generate: boilerplate generation (component/hook/service/test/api/model/util)
• health: project health score and recommendations
• analyze: project intelligence (structure/config/dependency/generate/apply)

Workflow

• workflow: lazy-load raw workflow assets (agents/skills/hooks/commands)
• init: scaffold .stackguide with stack-aware defaults
• agent: active workflow executor (status, intake, create_ticket, plan, verify, release)

Active Workflow Details

agent action:"intake"

• reads ticket from configured tracker
• returns normalized brief + gaps
• proposes branch name convention
• can optionally create a Jira ticket first (createFromDescription:true)

agent action:"create_ticket"

• creates Jira issues using strict MAIN DESCRIPTION format
• uses project defaults from .stackguide/config.json (projectKey, issueType)
• derives summary from first line of MAIN DESCRIPTION when omitted

agent action:"plan"

• inspects conventions + project shape
• creates vertical-slice plan
• returns exactly 3 target tests in structured format

agent action:"verify"

• executes configured tests/lint/build per layer
• checks branch naming + commit convention + TDD test budget
• returns blocker list and final pass/fail report

agent action:"release"

• checks CI status
• parses commits since last tag
• suggests semver impact (major / minor / patch)
• can create tag and PR/MR (when enabled)

Local Data And Security

init generates:

• .stackguide/config.json (project workflow config)

Runtime/local artifacts:

• .stackguide/analysis-cache.json
• .stackguide/health-history.json

These are machine-local and must not be committed.

Repository Guard

pnpm lint includes:

pnpm run guard:repo

The guard fails if .stackguide artifacts are tracked.

Integrity Hardening

Cache/history persistence includes:

• boundary/symlink checks
• file size and entry limits
• atomic write strategy
• checksum validation
• optional HMAC signature using:

STACKGUIDE_INTEGRITY_KEY=<long-random-secret>

For teams, configure STACKGUIDE_INTEGRITY_KEY in local/dev and CI environments for stronger tamper resistance.

Supported Stacks

python-django, python-fastapi, python-flask, react-node, react-typescript, vue-node, nextjs, express, nestjs, laravel, rails, golang, rust, custom.

Development

Use pnpm for all commands.

pnpm install
pnpm lint
pnpm test
pnpm build
pnpm dev

Release And Version Policy

• Current secure baseline: 4.1.2+
• Versions from 3.0.0 up to 4.1.1 are deprecated in npm due to local artifact hygiene issues.
• Use the latest 4.x release in all environments.

Registry Identifiers

• npm package: @stackguide/mcp-server
• MCP Registry server: io.github.isucorp-taimiralain/stackguide-mcp

License

GPL-3.0