RISEN Prompts MCP Server

A small, local, network-free Model Context Protocol server for the RISEN prompt-engineering framework. It gives any MCP client — Claude Desktop, Claude Code, and OpenAI Codex CLI — a shared set of tools to build, validate, save, and reuse structured prompts.

RISEN stands for Role · Instructions · Steps · Expectations · Narrowing.

Why this one

There are a few RISEN MCP servers floating around. This one is built around three commitments that the others don't state clearly:

• Runs entirely on your machine. The server code performs only local filesystem, stdio, and process coordination: no HTTP clients, sockets, telemetry, or external APIs. You can verify this in src/.
• Honest, deterministic logic. No fake "AI performance tracking" or hidden model calls. The validator uses transparent, documented heuristics and rates structural quality — it never pretends to guarantee a prompt will work.
• Real tests and a clean build. TypeScript, unit tests, an end-to-end MCP round-trip check, and a 10-gate verification script (npm run verify) that CI runs unchanged on Windows and Ubuntu — including a cross-process concurrency stress test and a 4000-case fuzz pass.

Tools

Tool	What it does
risen_build	Assemble the five components into a clean, ready-to-paste prompt + a quality score.
risen_validate	Score a prompt 0–100 with a per-component breakdown and specific suggestions.
risen_scaffold	Turn a plain task into a RISEN skeleton with the question each slot must answer.
risen_template_save	Save a reusable template (supports {{variables}}) to local storage.
risen_template_list	List saved templates, filterable by tag or query.
risen_template_get	Retrieve one template and its assembled prompt.
risen_template_delete	Delete a template.
risen_render	Substitute {{variables}} in a template and return the finished prompt.

It also exposes a risen_guide prompt that explains the framework, discoverable as a slash command in clients that support MCP prompts.

Install

From source

Requires Node.js 22 or newer.

git clone https://github.com/SYZBZ/risen-prompts-mcp.git
cd risen-prompts-mcp
npm install
npm run build
npm test        # optional: run the test suite

This produces dist/index.js, the server entry point.

Configure your client

Replace /absolute/path/to/risen-prompts-mcp with where you cloned the repo.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "risen-prompts": {
      "command": "node",
      "args": ["/absolute/path/to/risen-prompts-mcp/dist/index.js"]
    }
  }
}

Claude Code

claude mcp add risen-prompts -- node /absolute/path/to/risen-prompts-mcp/dist/index.js

Or add it to .mcp.json in your project root:

{
  "mcpServers": {
    "risen-prompts": {
      "command": "node",
      "args": ["/absolute/path/to/risen-prompts-mcp/dist/index.js"]
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.risen-prompts]
command = "node"
args = ["/absolute/path/to/risen-prompts-mcp/dist/index.js"]

Ready-to-copy versions of all three live in examples/.

Usage

Once connected, ask your assistant naturally — it will pick the right tool. For example:

"Use the RISEN tools to validate this prompt: role = a helpful assistant, instructions = write a blog post…"

"Scaffold a RISEN prompt for writing a cold outreach email."

"Save that as a template called 'Cold Email' with a {{recipient}} variable, then render it for recipient = a hiring manager."

The RISEN framework

Component	Purpose	Weak → Strong
Role	The persona/expertise the model adopts.	"an assistant" → "Senior Python developer with AWS experience"
Instructions	The core task, as a directive.	"help with code" → "Review the Django code for security vulnerabilities"
Steps	Ordered actions to follow.	(none) → 3+ concrete, sequential steps
Expectations	What a good output looks like.	"be good" → "bullet list, severity-tagged, ≤2 sentences each"
Narrowing	Constraints and scope.	(none) → "Do not comment on formatting; security only"

The validator awards up to 20 points per component (100 total). It rewards specificity, action verbs, measurable output targets, and explicit constraint language.

The semantic scoring cues are currently tuned for English. Prompts in other languages can still be assembled, stored, and rendered, but their validation scores may be lower than their actual structural quality.

Storage

Templates are stored as a single JSON file:

• Default: ~/.risen-mcp/templates.json
• Override with the RISEN_DATA_DIR environment variable.

It's plain JSON — you can read or back it up directly. Before editing it by hand, stop every RISEN MCP server that uses the same data directory.

Writes are atomic and guarded by a cross-process lock so multiple MCP clients cannot overwrite each other's changes. Invalid or malformed JSON is reported and left untouched instead of being silently replaced. New storage directories and files use owner-only permissions on platforms that support POSIX modes. Locks record an owner token and process ID; a later writer automatically recovers a lock abandoned by a terminated process. If ownership cannot be confirmed safely, the write stops with a recovery message instead of guessing. After confirming no RISEN server is running, that message may ask you to remove .templates.lock and .templates.lock.recovery before retrying.

Development

npm run build   # compile TypeScript to dist/
npm test        # build, then run unit + storage + MCP stdio tests
npm run verify  # full 10-gate check: strict types, tests, cross-process
                # concurrency stress, fuzz invariants, packaging, hygiene

Core logic lives in src/risen.ts as pure functions with no I/O, so it's easy to test and reuse. CI runs the same scripts/verify.sh on a Windows + Ubuntu matrix, so a green local run means CI confirms rather than discovers.

Known dependency advisories

npm audit currently reports two moderate advisories for @hono/node-server (GHSA-frvp-7c67-39w9), pulled in transitively by @modelcontextprotocol/sdk. They are intentionally left as-is:

• The vulnerable code is Hono's HTTP serve-static handler. This server is stdio-only — it never starts an HTTP server, so that path is unreachable.
• The SDK version in use is the latest available; npm audit fix --force would downgrade it to 1.24.3, a breaking change, without making this server safer.

CI still enforces npm audit --omit=dev --audit-level=high, so any high or critical advisory in production dependencies fails the build.

License

MIT — see LICENSE.