io.github.isucorp-taimiralain/stackguide-mcp

Official

by isucorp-taimiralain · TypeScript

Dynamic context loading for AI assistants with TDD workflow and AST analysis

Dynamic context loading with TDD workflow and AST analysis for AI assistants.

README.md7 KBView on GitHub

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

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

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.

json

{
  "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.

json

{
  "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.

json

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

How To Use (Any IDE)

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

Quick Start

Configure your project:

bash

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

Check generated setup:

bash

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

Run active TDD workflow:

bash

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:

bash

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:

bash

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.

bash

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

Install

claude_desktop_config.json

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