prompyai-mcp 0.1.2 → 0.1.4

package/README.md

@@ -1,70 +1,71 @@
 # prompyai-mcp
 
-Context-aware prompt intelligence MCP server for Claude CLI. Scores your developer prompts against your real codebase, suggests improvements, and rewrites enhanced prompts.
+Context-aware prompt intelligence MCP server for Claude CLI. Scores your prompts against your real codebase and rewrites them with AI.
 
-## What it does
+## Install
 
-When you write a prompt in Claude CLI, PrompyAI automatically analyzes it against your actual project — files, tech stack, conventions, session history — and returns:
+```bash
+claude mcp add prompyai -- npx prompyai-mcp serve
+```
 
-- **Score** (0-100) across 4 dimensions: specificity, context, clarity, anchoring
-- **Suggestions** with concrete examples tailored to your project
-- **Enhanced prompt** rewritten with the improvements applied
+No sign-up. No config. Works immediately. Requires Node.js 20+.
 
-```
-Prompt Score: 28/100 [F]
-Session context: 12 file references carried forward
-
-  Specificity        6/25  ===...........
-  Context            5/25  ==............
-  Clarity           10/25  ======........
-  Anchoring          7/25  ====..........
-
-This prompt is too vague for good results. Critical fixes:
-  1. Replace "fix" with what's actually broken
-     > "debug the JWT validation error in @src/middleware/auth.ts"
-  2. Describe expected vs actual behavior
-     > "should return 200 but returns 401 when token has role claim"
-
-Enhanced prompt:
-```​
-In @src/middleware/auth.ts, the JWT validation returns 401 for valid
-tokens. Update validateToken to extract the role claim correctly.
-Ensure existing vitest tests pass.
-```​
-```
+## What It Does
 
-## Install
+Every time you write a prompt in Claude CLI, PrompyAI automatically:
+
+1. **Scores it** (0–100) across Specificity, Context Completeness, Task Clarity, and File & Folder Anchoring
+2. **Suggests improvements** tailored to your project
+3. **Rewrites the prompt** with real file paths, verified symbols, and codebase context
 
-```bash
-npm install -g prompyai-mcp
 ```
+Prompt Score: 43/100 [D]
 
-Requires Node.js 20+.
+  Specificity         3/25  ==..............
+  Context Completeness 13/25  ========........
+  Task Clarity        15/25  =========.......
+  File & Folder Anchoring 10/25  ======..........
 
-## Setup with Claude CLI
+Key improvements:
+  1. Expand your prompt with more context
+  2. Add file paths using @mentions
+  3. Specify what format you expect the output in
 
-```bash
-claude mcp add prompyai -- npx prompyai-mcp serve
+Try something more like:
+
+  "Build the VS Code extension in packages/vscode-extension/ that integrates
+   with the PrompyAI MCP server at packages/mcp-server/. It should provide
+   real-time prompt scoring in the editor sidebar, show score breakdowns
+   (specificity, context, clarity, anchoring), and offer a 'rewrite prompt'
+   action. Use the shared types from packages/shared/."
 ```
 
-Or add to `~/.claude/claude_desktop_config.json`:
+## AI Enhancement — Works for Everyone
 
-```json
-{
-  "mcpServers": {
-    "prompyai": {
-      "command": "npx",
-      "args": ["prompyai-mcp", "serve"]
-    }
-  }
-}
-```
+PrompyAI uses a two-layer architecture:
+
+- **API key users** (`ANTHROPIC_API_KEY` set) → PrompyAI calls Claude Haiku directly for fast AI rewrites
+- **Subscription users** (no API key) → PrompyAI returns rich codebase context to Claude, which generates the enhanced prompt using your existing session
+
+All users get AI-enhanced output. No separate API key required.
+
+## How It Knows Your Codebase
+
+PrompyAI indexes your project locally:
+
+- **File tree** — structure, key folders, recently modified files
+- **Tech stack** — language, framework, ORM, test runner detection
+- **Code symbols** — functions, classes, interfaces extracted via the TypeScript Compiler API
+- **Git state** — branch, dirty files, recent changes
+- **Session history** — reads Claude Code conversation transcripts for multi-turn context
+
+All indexing happens locally. Nothing is sent externally (except optional anonymous telemetry).
 
 ## MCP Tools
 
 ### `evaluate_prompt`
 
-Automatically called on every user message. Scores a prompt against your project codebase.
+Auto-called on every user message. Scores your prompt against your project.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
@@ -73,11 +74,9 @@ Automatically called on every user message. Scores a prompt against your project
 | `active_file` | no | Currently open file path |
 | `session_id` | no | Claude Code session ID for multi-turn context |
 
-Returns a JSON result with a pre-formatted `display` field that Claude shows directly.
-
 ### `get_context`
 
-Returns a summary of your project: detected tech stack, recently modified files, key folders, and AI instruction summaries.
+Returns your project summary: tech stack, recent files, key folders.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
@@ -85,50 +84,29 @@ Returns a summary of your project: detected tech stack, recently modified files,
 
 ### `prompyai_toggle`
 
-Turns auto-evaluation on or off. Enabled by default. Say "pause prompyai" or "enable prompyai" in Claude CLI.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `enabled` | yes | `true` to enable, `false` to disable |
-
-## Scoring Dimensions
+Turn auto-evaluation on or off. Say "pause prompyai" or "enable prompyai" in Claude CLI.
 
-Each dimension scores 0-25, total 0-100.
+## Desktop Config
 
-| Dimension | Measures |
-|-----------|----------|
-| **Specificity** | Concrete actions vs vague verbs, output format, constraints |
-| **Context** | File references, error messages, expected vs actual behavior |
-| **Clarity** | Single focused task, success criteria, unambiguous language |
-| **Anchoring** | File paths, project entity references, hot file mentions |
+Alternatively, add to `~/.claude/claude_desktop_config.json`:
 
-**Grades:** A (90+), B (70+), C (50+), D (30+), F (<30)
-
-## Features
-
-- **Session-aware** — Reads Claude Code JSONL transcripts for multi-turn context
-- **Multi-agent aware** — Includes subagent research in scoring context
-- **Monorepo support** — Detects tech stacks across workspace packages
-- **AI-powered suggestions** — Claude Haiku generates context-aware improvements
-- **Template fallback** — Works without an API key using heuristic scoring
-- **Rate limiting** — 100 AI calls/day per machine, graceful fallback
-- **Anonymous telemetry** — Usage stats only, opt-out with `PROMPYAI_TELEMETRY=false`
-
-## AI-Powered Suggestions
-
-When `ANTHROPIC_API_KEY` is set, PrompyAI uses Claude Haiku to generate context-aware suggestions grounded in your project structure. Without an API key, it falls back to smart template-based suggestions from the heuristic analysis.
-
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
+```json
+{
+  "mcpServers": {
+    "prompyai": {
+      "command": "npx",
+      "args": ["prompyai-mcp", "serve"]
+    }
+  }
+}
 ```
 
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `ANTHROPIC_API_KEY` | No | Enables AI-powered suggestions via Claude Haiku |
+| `ANTHROPIC_API_KEY` | No | Enables direct AI suggestions via Claude Haiku (optional) |
 | `PROMPYAI_TELEMETRY` | No | Set to `false` to opt out of anonymous telemetry |
-| `PROMPYAI_TELEMETRY_URL` | No | Override telemetry endpoint URL |
 
 ## CLI Commands
 
@@ -138,12 +116,6 @@ prompyai doctor             # Run environment diagnostics
   --workspace <path>        # Workspace to check (default: cwd)
 ```
 
-## Rate Limits
-
-- **Per machine:** 100 AI-enhanced evaluations per day
-- **Global:** Monthly cost cap
-- **When limits hit:** Heuristic scoring continues, AI suggestions paused
-
 ## Programmatic API
 
 ```typescript
@@ -160,6 +132,12 @@ console.log(result.total);   // 0-100
 console.log(result.grade);   // A-F
 ```
 
+## Links
+
+- **Website:** [prompyai.com](https://prompyai.com)
+- **GitHub:** [github.com/samouh-waleed/PrompyAI](https://github.com/samouh-waleed/PrompyAI)
+- **MCP Registry:** [io.github.samouh-waleed/prompyai](https://registry.modelcontextprotocol.io)
+
 ## License
 
 MIT

package/dist/cli.js

@@ -2657,7 +2657,7 @@ var init_telemetry = __esm({
     BATCH_INTERVAL_MS = 3e4;
     MAX_BATCH_SIZE = 50;
     VERSION = "0.1.0";
-    TelemetryClient = class {
+    TelemetryClient = class _TelemetryClient {
       buffer = [];
       timer = null;
       enabled;
@@ -2668,6 +2668,7 @@ var init_telemetry = __esm({
           if (this.timer.unref) this.timer.unref();
         }
       }
+      static IMMEDIATE_EVENTS = /* @__PURE__ */ new Set(["server_start"]);
       track(event, properties) {
         if (!this.enabled) return;
         this.buffer.push({
@@ -2677,7 +2678,7 @@ var init_telemetry = __esm({
           timestamp: Date.now(),
           properties
         });
-        if (this.buffer.length >= MAX_BATCH_SIZE) {
+        if (this.buffer.length >= MAX_BATCH_SIZE || _TelemetryClient.IMMEDIATE_EVENTS.has(event)) {
           this.flush();
         }
       }
@@ -2697,13 +2698,12 @@ var init_telemetry = __esm({
         } catch {
         }
       }
-      shutdown() {
+      async shutdown() {
         if (this.timer) {
           clearInterval(this.timer);
           this.timer = null;
         }
-        this.flush().catch(() => {
-        });
+        await this.flush();
       }
     };
     telemetry = new TelemetryClient();
@@ -2832,7 +2832,7 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
-var server, indexer, scorer, rateLimiter, transport;
+var server, indexer, scorer, rateLimiter, gracefulShutdown, transport;
 var init_server = __esm({
   async "src/mcp/server.ts"() {
     "use strict";
@@ -2907,13 +2907,15 @@ var init_server = __esm({
     process.on("unhandledRejection", (error) => {
       logError("Unhandled rejection", error);
     });
-    process.on("SIGINT", () => {
-      telemetry.shutdown();
+    gracefulShutdown = async () => {
+      await telemetry.shutdown();
       process.exit(0);
+    };
+    process.on("SIGINT", () => {
+      gracefulShutdown();
     });
     process.on("SIGTERM", () => {
-      telemetry.shutdown();
-      process.exit(0);
+      gracefulShutdown();
     });
     transport = new StdioServerTransport();
     await server.connect(transport);