pstack-mcp

MCP server that exposes the pstack Agent Skills collection to any LLM-powered environment — LM Studio, and other MCP hosts.

Why pstack-mcp?

We first want to extend our sincere gratitude to poteto and the pstack community for sharing such a rich collection of agent skills with the world. The pstack skills are extraordinary — they give agents a shared language for collaboration, a deep toolbox of engineering principles, and battle-tested playbooks.

However, pstack has lived primarily as a Cursor plugin. That is wonderful, and deeply appreciated. But it also means that the same skills have been out of reach for the many other LLM environments where agents still need guidance: LM Studio's local model runtime, standalone MCP servers, and any environment where a model needs to reach out and fetch the right skill at just the right moment.

pstack-mcp was born from one simple idea: what if the same pstack skills could be available to every LLM, in every environment, on demand?

pstack-mcp makes that a reality. It packages the full pstack skill collection behind a clean MCP tool interface. When a small or large model is working through a task and hits a gap — "how do I structure this refactoring?", "what principle should guide this design?", "how do I reproduce a flaky test?" — it can simply call the right pstack-mcp tool, get the full skill content, and return to the task with the guidance it needed. No plugin install. No context limits. Just ask, receive, continue.

Related MCP server: dsh-skills-anywhere

What pstack-mcp provides

pstack-mcp exposes 13 MCP tools that give any LLM on-demand access to:

Usage examples

Example 1 — A model hits a design decision and needs guidance:

// Ask: "I'm refactoring a React component and need a systematic approach."
// Tool call:
{
  "tool": "playbook-route",
  "parameters": {
    "task": "refactor a large React component into smaller hooks and components",
    "limit": 3
  }
}

pstack-mcp responds with the matching playbook, recommended skills, and a ready-to-type prompt — the model can now execute the refactoring with confidence.

Example 2 — A model needs to verify a test before merging:

// Ask: "I have a failing test for a Counter state machine. Help me write a proper test."
// Tool call:
{
  "tool": "recommend_skills",
  "parameters": {
    "task": "write a test for a React state machine using statechart",
    "limit": 3
  }
}

pstack-mcp recommends statechart, tdd, and blast-radius — the model now has the exact skills it needs.

Example 3 — A model hits an error and needs a debugging principle:

// Ask: "My app has a race condition I can't reproduce. What principle should I apply?"
// Tool call:
{
  "tool": "get_principles",
  "parameters": {
    "names": ["fix-root-causes", "sequence-verifiable-units"],
    "mode": "full"
  }
}

The model receives the full principle text and can apply the systematic debugging approach immediately.

Using pstack-mcp in your prompt

Before running pstack-mcp tools, you may want to give the LLM context about what pstack-mcp can do. There are two recommended approaches:

Approach A — Include the skill document directly in your prompt:

Copy the contents of skills/pstack-mcp.md into your system prompt or user message before describing the task. This tells the model exactly what tools are available and how to use them:

Here is the pstack-mcp skill file. Keep it in context and use these tools whenever you need a skill, principle, or playbook to guide your work.

Then follow with your actual task description. The model will know to reach out for recommend_skills, playbook-route, get_principles, etc. when it hits a gap.

Approach B — Use a RAG tool to load the file:

If you are using an RAG (Retrieval-Augmented Generation) tool like read_document, fetch_web_content, or a vector-store retrieval tool, you can load skills/pstack-mcp.md on demand instead of keeping the full text in context. The RAG tool fetches the skill document, the model reads it, then the model calls pstack-mcp tools as needed.

Either way, the workflow is the same:

1. Load skills/pstack-mcp.md (or reference it).

2. Describe your task.

3. Let the model decide which tool to call based on what it needs.

4. The model continues the task with the returned skill content.

Working from real examples

If you want concrete, copy-paste examples to adapt for your own work, check the examples/ directory. Each file covers a specific engineering scenario — bug fixing with verification, refactoring with behavioral anchors, investigation before changes, feature design with multi-model comparison, test-first development, dependency upgrade analysis, and long-running unattended work with audit trails. Read through the examples, pick the one closest to your current task, and adapt the tool calls to your specific codebase and requirements. The goal is to show you how real pstack usage patterns translate into MCP tool calls, not to provide a one-size-fits-all script.

Installation

Option A — LM Studio Plugin

Method 1:

lms get hoonowng/pstack-mcp

Method 2:

1. Clone this repository:

git clone https://github.com/Nowng/pstack-mcp.git
cd pstack-mcp
npm install
npm run build

2. Copy the plugin to your LM Studio plugins directory:

cp -r .lmstudio ~/.lmstudio/extensions/plugins/pstack

3. Enable it in LM Studio settings. The plugin will automatically discover the pstack/ skills directory at build time.

Option B — Standalone MCP server

1. Clone this repository and install dependencies:

git clone https://github.com/Nowng/pstack-mcp.git
cd pstack-mcp
npm install
npm run build

2. Add to your mcp.json:

{
  "mcpServers": {
    "pstack": {
      "command": "node",
      "args": ["/absolute/path/to/pstack-mcp/dist/server.js"],
      "env": {
        "PSTACK_ROOT": "/absolute/path/to/pstack-mcp/pstack"
      }
    }
  }
}

Troubleshooting

• "PSTACK_ROOT/pstack/automations/benny not found": Ensure the pstack/ directory (the skill clone) exists inside your pstack-mcp project root. The directory pstack/automations/benny/skills/ must contain subdirectories like reproduce-and-fix-issues/, triage-issue-reports/, setup-benny/ with their respective SKILL.md files.

• "pstack-models.mdc not found": The model-setup tool looks for ~/.cursor/rules/pstack-models.mdc or $PSTACK_ROOT/pstack-models.mdc. If you haven't created this file yet, the tool will return a helpful message listing where to place it.

• LM Studio plugin not appearing: Restart LM Studio after copying the .lmstudio/plugins/pstack directory. Check ~/.lmstudio/plugins/pstack/manifest.json for valid JSON.

• MCP server won't start: Run node dist/server.js directly and check stderr for import errors. Ensure Node.js ≥ 18 and all dependencies are installed.

License

This server skeleton is licensed under MIT. The pstack skill content — all SKILL.md files, playbooks, principles, and automation templates — is the work of its upstream authors under the pstack project license. Please respect upstream licensing when distributing or modifying pstack content.

Architecture

pstack/                    ← skill content (cloned from upstream)
  ├── automations/benny/
  │   └── skills/<name>/SKILL.md
  └── skills/<name>/SKILL.md

src/
  ├── tool-definitions.ts  ← single source of truth for all 13 tools
  ├── phase4-tools.ts      ← model-setup + automate-workflow implementations
  ├── server.ts            ← MCP server (stdio transport)
  ├── index.ts             ← LM Studio plugin entry point
  └── ...

The tool definitions are generated from src/tool-definitions.ts — both the MCP server and LM Studio plugin share the same source of truth.