Release/0.1.1 (#13)

* chore: update documentation and version for required projectPath parameter

- Updated CHANGELOG.md to document the release of version 0.1.1.
- Corrected `projectPath` parameter in documentation to mark it as required for `logicstamp_refresh_snapshot`, including explanations and examples.
- Updated package.json and package-lock.json to reflect the new version 0.1.1.
- Enhanced error handling in tests to ensure proper validation of the required `projectPath` parameter.

* docs: clarify projectPath requirement and streamline parameter descriptions in README.md

Author: AmiteK23

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.1] - 2025-12-14
+
+### Fixed
+
+- **Documentation Fix** - Corrected `projectPath` parameter documentation for `logicstamp_refresh_snapshot`
+  - Updated docs to correctly mark `projectPath` as required (was incorrectly marked as optional)
+  - Added explanation of why `projectPath` is required (prevents hangs when `stamp init` has been run)
+  - Updated all examples to include `projectPath` parameter
+  - Fixes issue where users following documentation would encounter errors when omitting `projectPath`
+
 ## [0.1.0] - 2025-12-13
 
 ### Added

README.md

@@ -4,6 +4,12 @@
   <img src="./assets/logicstamp-fox.svg" alt="LogicStamp Fox Mascot" width="120" height="120">
 </div>
 
+![Version](https://img.shields.io/badge/version-0.1.1-blue.svg)
+![Beta](https://img.shields.io/badge/status-beta-orange.svg)
+![License](https://img.shields.io/badge/license-MIT-green.svg)
+![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)
+[![CI](https://github.com/LogicStamp/logicstamp-mcp/workflows/CI/badge.svg)](https://github.com/LogicStamp/logicstamp-mcp/actions)
+
 Model Context Protocol (MCP) server for [LogicStamp Context](https://github.com/LogicStamp/logicstamp-context) - enabling AI assistants to safely analyze and understand React/TypeScript codebases.
 
 ## Overview
@@ -86,9 +92,10 @@ The MCP server provides 6 tools. For complete API documentation with input/outpu
 ### Quick Reference
 
 **logicstamp_refresh_snapshot** - Create a snapshot of the current codebase state (STEP 1)
-- Parameters: `profile` (optional), `mode` (optional), `includeStyle` (optional), `projectPath` (optional), `cleanCache` (optional)
+- Parameters: `profile` (optional), `mode` (optional), `includeStyle` (optional), `projectPath` (required), `cleanCache` (optional)
 - Returns: `snapshotId`, `summary`, `folders`
 - **Always call this first** when analyzing a new repo
+- **Note:** `projectPath` is REQUIRED - must be an absolute path to the project root. Omitting this parameter can cause the server to hang.
 - Cache is automatically cleaned if corruption is detected
 
 **logicstamp_list_bundles** - List available bundles for selective loading (STEP 2)
@@ -105,7 +112,7 @@ The MCP server provides 6 tools. For complete API documentation with input/outpu
 - Parameters: 
   - `profile` (optional): Analysis profile (default: `llm-chat`)
   - `mode` (optional): Code inclusion mode (default: `header`)
-  - `includeStyle` (optional): Include style metadata in comparison. Only takes effect when `forceRegenerate` is `true`. When `forceRegenerate` is `false`, compares whatever style metadata exists on disk (may be incomplete) (default: `false`)
+  - `includeStyle` (optional): Include style metadata in comparison. Only takes effect when `forceRegenerate` is `true` (default: `false`)
   - `forceRegenerate` (optional): Force regeneration of context before comparing. When `false`, reads existing `context_main.json` from disk (fast). When `true`, runs `stamp context` to regenerate (default: `false`)
   - `projectPath` (optional): Project path (defaults to current directory)
   - `baseline` (optional): Comparison baseline: `disk` (default), `snapshot`, or custom path

docs/commands/refresh-snapshot.md

@@ -52,10 +52,9 @@
   - Visual consistency checks
   - When the user asks about styling, colors, spacing, animations, or visual design
 
-### `projectPath` (optional)
+### `projectPath` (required)
 - **Type:** `string`
-- **Default:** Current working directory (or `PROJECT_PATH` environment variable)
-- **Description:** Absolute path to the project root. If not provided, uses the current directory.
+- **Description:** **CRITICAL: Absolute path to project root. REQUIRED - must always be provided.** When `stamp init` has been run, MCP clients may omit this parameter, causing hangs. This parameter is REQUIRED for the tool to work correctly. The server will resolve relative paths to absolute paths automatically.
 
 ### `cleanCache` (optional)
 - **Type:** `boolean`
@@ -116,18 +115,21 @@ Array of folder metadata objects, each containing:
 ```json
 {
   "name": "logicstamp_refresh_snapshot",
-  "arguments": {}
+  "arguments": {
+    "projectPath": "/absolute/path/to/project"
+  }
 }
 ```
 
-This creates a snapshot with default settings (`profile: 'llm-chat'`, `mode: 'header'`, `includeStyle: false`).
+This creates a snapshot with default settings (`profile: 'llm-chat'`, `mode: 'header'`, `includeStyle: false`). **Note:** `projectPath` is required.
 
 ### With Custom Profile
 
 ```json
 {
   "name": "logicstamp_refresh_snapshot",
   "arguments": {
+    "projectPath": "/absolute/path/to/project",
     "profile": "llm-safe"
   }
 }
@@ -139,6 +141,7 @@ This creates a snapshot with default settings (`profile: 'llm-chat'`, `mode: 'he
 {
   "name": "logicstamp_refresh_snapshot",
   "arguments": {
+    "projectPath": "/absolute/path/to/project",
     "includeStyle": true
   }
 }
@@ -150,6 +153,7 @@ This creates a snapshot with default settings (`profile: 'llm-chat'`, `mode: 'he
 {
   "name": "logicstamp_refresh_snapshot",
   "arguments": {
+    "projectPath": "/absolute/path/to/project",
     "mode": "full"
   }
 }

docs/mcp_integration.md

@@ -73,7 +73,7 @@ logicstamp-context/
 - `profile` (optional): `llm-chat` (default) | `llm-safe` | `ci-strict`
 - `mode` (optional): `header` (default) | `full` | `none`
 - `includeStyle` (optional): Include style metadata (default: `false`)
-- `projectPath` (optional): Defaults to current working directory
+- `projectPath` (required): **CRITICAL: Absolute path to project root. REQUIRED - must always be provided.** When `stamp init` has been run, MCP clients may omit this parameter, causing hangs. This parameter is REQUIRED for the tool to work correctly. The server will resolve relative paths to absolute paths automatically.
 - `cleanCache` (optional): Force cache cleanup (default: `false`, auto-detects corruption)
 
 **Behavior**:

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "logicstamp-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP server for LogicStamp Context - analyze React/TypeScript codebases",
   "type": "module",
   "main": "./dist/index.js",

package.json

@@ -18,6 +18,7 @@ import { readBundle } from './tools/read-bundle.js';
 import { compareSnapshot } from './tools/compare-snapshot.js';
 import { compareModes } from './tools/compare-modes.js';
 import { readLogicStampDocs } from './tools/read-logicstamp-docs.js';
+import type { RefreshSnapshotInput } from '../types/schemas.js';
 
 /**
  * Create and configure the MCP server
@@ -264,7 +265,10 @@ export function createServer(): Server {
 
       switch (name) {
         case 'logicstamp_refresh_snapshot': {
-          const result = await refreshSnapshot(args || {});
+          // Type assertion is safe here because:
+          // 1. MCP framework validates JSON schema (which requires projectPath)
+          // 2. refreshSnapshot function validates projectPath at runtime and throws clear error if missing
+          const result = await refreshSnapshot((args || {}) as unknown as RefreshSnapshotInput);
           return {
             content: [
               {

src/mcp/server.ts

@@ -82,7 +82,7 @@ export interface RefreshSnapshotInput {
   profile?: 'llm-chat' | 'llm-safe' | 'ci-strict';
   mode?: 'header' | 'full' | 'none';
   includeStyle?: boolean; // Include style metadata (equivalent to stamp context style)
-  projectPath?: string;
+  projectPath: string; // REQUIRED: Absolute path to project root
   cleanCache?: boolean; // Manually force cache cleanup (default: false, auto-detects corruption)
 }
 

src/types/schemas.ts

@@ -188,6 +188,12 @@ describe('refreshSnapshot integration tests', () => {
   });
 
   describe('error handling', () => {
+    it('should throw error when projectPath is missing', async () => {
+      await expect(
+        refreshSnapshot({} as any)
+      ).rejects.toThrow('projectPath is REQUIRED');
+    });
+
     it('should throw error when stamp command fails', async () => {
       mockExecImpl.mockImplementation((command: string, options: any, callback: any) => {
         if (callback) {