# RISEN Prompts MCP Server

[![CI](https://github.com/SYZBZ/risen-prompts-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/SYZBZ/risen-prompts-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

A small, **local, network-free** [Model Context Protocol](https://modelcontextprotocol.io) 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 **R**ole · **I**nstructions · **S**teps · **E**xpectations · **N**arrowing.

## 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/`](./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.

```bash
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):

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

### Claude Code

```bash
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:

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

### OpenAI Codex CLI

Add to `~/.codex/config.toml`:

```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/`](./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

```bash
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](https://github.com/advisories/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](./LICENSE).