lotus-wisdom-mcp 0.2.1 → 0.3.1

package/README.md

@@ -4,6 +4,8 @@
   <img src="assets/lotus-flower.png" alt="Lotus Flower" width="400"/>
 </p>
 
+[![smithery badge](https://smithery.ai/badge/@linxule/lotus-wisdom-mcp)](https://smithery.ai/server/@linxule/lotus-wisdom-mcp)
+
 An MCP server implementation that provides a tool for problem-solving using the Lotus Sutra's wisdom framework, combining analytical thinking with intuitive wisdom.
 
 ## Features
@@ -27,7 +29,10 @@ The server implements a structured thinking process using wisdom domains inspire
 
 ### Wisdom Domains and Tags
 
-The server organizes thoughts using five wisdom domains (all valid values for the `tag` input parameter):
+The server organizes thoughts using wisdom domains (all valid values for the `tag` input parameter):
+
+* **Entry** (🚪): `begin`
+  - Begin your journey here - receives the full framework before contemplation starts
 
 * **Skillful Means** (🔆): `upaya`, `expedient`, `direct`, `gradual`, `sudden`
   - Different approaches to truth - sometimes direct pointing, sometimes gradual unfolding
@@ -59,12 +64,13 @@ Note: The visualization appears in the server console output, helping developers
 ### Process Flow
 
 1. The user submits a problem to solve
-2. The model works through a sequence of thoughts using different tags
-3. Each thought builds on previous ones and may revise understanding
-4. The tool tracks both the tag journey and wisdom domain movements
-5. Meditation pauses can be included for clarity
-6. When status='WISDOM_READY' is returned, the tool's work is complete
-7. The model then expresses the final wisdom naturally in its own voice
+2. The model begins with `tag='begin'` to receive the full framework
+3. The model continues with contemplation tags (open, examine, integrate, etc.)
+4. Each thought builds on previous ones and may revise understanding
+5. The tool tracks both the tag journey and wisdom domain movements
+6. Meditation pauses can be included for clarity
+7. When status='WISDOM_READY' is returned, the tool's work is complete
+8. The model then expresses the final wisdom naturally in its own voice
 
 ## Available Tools
 
@@ -72,6 +78,8 @@ Note: The visualization appears in the server console output, helping developers
 
 A tool for problem-solving using the Lotus Sutra's wisdom framework, with various approaches to understanding.
 
+**Begin your journey with `tag='begin'`** - this returns the full framework (philosophy, domains, guidance) to ground your contemplation. Then continue with the other tags.
+
 **Inputs:**
 
 * `tag` (string, required): The current processing technique (must be one of the tags listed above)
@@ -115,60 +123,72 @@ Here's how a conversation with Claude might flow when using the Lotus Wisdom MCP
 
 **User**: "Help me understand the relationship between freedom and responsibility."
 
-**Claude** would then use the lotuswisdom tool through multiple steps:
+**Claude** would begin the journey with `tag='begin'` to receive the framework, then continue:
+
+1. First, enter the contemplative space:
+```json
+{
+  "tag": "begin",
+  "content": "Entering contemplation on freedom and responsibility.",
+  "stepNumber": 1,
+  "totalSteps": 6,
+  "nextStepNeeded": true
+}
+```
+→ Returns `FRAMEWORK_RECEIVED` with full framework
 
-1. First, establish an opening thought:
+2. Then, establish an opening thought:
 ```json
 {
   "tag": "open",
   "content": "The question explores the relationship between freedom and responsibility, which contain an apparent tension but also deep connection.",
-  "stepNumber": 1,
-  "totalSteps": 5,
+  "stepNumber": 2,
+  "totalSteps": 6,
   "nextStepNeeded": true
 }
 ```
 
-2. Then engage with different perspectives:
+3. Engage with different perspectives:
 ```json
 {
   "tag": "direct",
   "content": "Freedom and responsibility are two sides of the same coin. True freedom isn't absence of constraints but the capacity to choose our response within constraints.",
-  "stepNumber": 2,
-  "totalSteps": 5,
+  "stepNumber": 3,
+  "totalSteps": 6,
   "nextStepNeeded": true
 }
 ```
 
-3. Perhaps take a meditation pause:
+4. Perhaps take a meditation pause:
 ```json
 {
   "tag": "meditate",
   "content": "Contemplating how freedom without responsibility becomes chaos, and responsibility without freedom becomes oppression.",
-  "stepNumber": 3,
-  "totalSteps": 5,
+  "stepNumber": 4,
+  "totalSteps": 6,
   "nextStepNeeded": true,
   "isMeditation": true
 }
 ```
 
-4. Integrate the understanding:
+5. Integrate the understanding:
 ```json
 {
   "tag": "integrate",
   "content": "Freedom and responsibility mutually enable each other. Our freedom to choose gives rise to our responsibility for what we choose, and our willingness to take responsibility expands our freedom.",
-  "stepNumber": 4,
-  "totalSteps": 5,
+  "stepNumber": 5,
+  "totalSteps": 6,
   "nextStepNeeded": true
 }
 ```
 
-5. Express the final understanding:
+6. Express the final understanding:
 ```json
 {
   "tag": "express",
   "content": "The paradox resolves when we see that authentic freedom includes responsibility as its natural expression.",
-  "stepNumber": 5,
-  "totalSteps": 5,
+  "stepNumber": 6,
+  "totalSteps": 6,
   "nextStepNeeded": false
 }
 ```
@@ -293,6 +313,21 @@ The Lotus Wisdom framework recognizes that wisdom often emerges not through line
 
 5. **Natural Expression**: The tool handles the contemplative process, but the final wisdom is always expressed naturally by the AI, not as formatted output.
 
+### Token Optimization Design
+
+MCP tool descriptions stay in the AI's context window constantly when the server is connected. To minimize this overhead while preserving the full teaching content:
+
+- **Constant context (~150 tokens)**: The `lotuswisdom` tool description is kept minimal—just enough for the AI to know when and how to use it
+- **On-demand learning (~1,200 tokens)**: The complete framework is delivered when calling with `tag='begin'`, including:
+  - Philosophy and domain spirits
+  - Parameter explanations (tag, content, stepNumber, etc.)
+  - Response format details (wisdomDomain, journey, domainJourney)
+  - Meditation handling (MEDITATION_COMPLETE status)
+  - When to use guidance
+- **Learn first, practice second**: The `begin` tag ensures models receive complete understanding before contemplating
+
+This approach reduces constant context overhead by ~85% when the tool is idle. When actually used, the full framework is delivered on first step—nothing is lost.
+
 ## License
 
 This MCP server is licensed under the MIT License. For more details, please see the LICENSE file in the project repository.
@@ -303,7 +338,19 @@ Contributions are welcome! Please feel free to submit issues or pull requests on
 
 ## Version
 
-Current version: 0.2.1
+Current version: 0.3.1
+
+### What's New in 0.3.1
+
+- 📚 **Complete Framework Learning**: `begin` tag now returns full parameter explanations, response format details, and meditation handling
+- 🔢 **Accurate Token Counts**: Updated documentation with actual token measurements (~150 constant, ~1,200 on-demand)
+
+### What's New in 0.3.0
+
+- 🚪 **Begin Tag**: New `tag='begin'` opens the journey—returns full framework before contemplation starts
+- ⚡ **Optimized Token Footprint**: Reduced constant context overhead from ~1400 to ~200 tokens while preserving full teaching content
+- 🧘 **Learn First, Practice Second**: The `begin` tag ensures models receive complete understanding before contemplating
+- 📦 **Updated SDK**: Upgraded to @modelcontextprotocol/sdk 1.23.0
 
 ### What's New in 0.2.1
 

package/dist/bundle.js

@@ -12437,6 +12437,8 @@ var source_default = chalk;
 
 // index.ts
 var WISDOM_DOMAINS = {
+  "entry": ["begin"],
+  // Always call first to receive framework
   "skillful_means": ["upaya", "expedient", "direct", "gradual", "sudden"],
   "non_dual_recognition": ["recognize", "transform", "integrate", "transcend", "embody"],
   "meta_cognitive": ["examine", "reflect", "verify", "refine", "complete"],
@@ -12484,7 +12486,7 @@ var LotusWisdomServer = class {
     if (typeof data.nextStepNeeded !== "boolean") {
       throw new Error("Invalid nextStepNeeded: must be a boolean");
     }
-    if (data.stepNumber === 1 && data.tag === "open") {
+    if (data.stepNumber === 1) {
       this.resetProcess();
     }
     return {
@@ -12556,6 +12558,90 @@ var LotusWisdomServer = class {
       }
       this.thoughtProcess.push(validatedInput);
       this.log(this.formatThought(validatedInput));
+      if (validatedInput.tag === "begin") {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              status: "FRAMEWORK_RECEIVED",
+              welcome: "Welcome to the Lotus Wisdom framework. Read this before continuing your contemplative journey.",
+              philosophy: {
+                core: "The Lotus Sutra teaches that there are many skillful means to reach the same truth. These tags are not rigid steps but different aspects of wisdom that interpenetrate and respond to what each moment needs.",
+                essence: "The wisdom channels itself through your choices. Each step contains all others\u2014when you truly recognize, you are already transforming. The tool simply mirrors your journey without judgment.",
+                trust: "Trust what each moment calls for. The path reveals itself in the walking."
+              },
+              domains: {
+                process_flow: {
+                  tags: ["open", "engage", "express"],
+                  spirit: "The natural arc of inquiry. Opening creates space for what wants to emerge. Engagement explores with curiosity and presence. Expression shares what arose\u2014not as conclusion, but as offering.",
+                  role: "A container that can hold any of the other approaches within it."
+                },
+                skillful_means: {
+                  tags: ["upaya", "expedient", "direct", "gradual", "sudden"],
+                  spirit: "Many ways lead to understanding. Sometimes direct pointing cuts through confusion instantly. Sometimes patient, gradual unfolding is what serves. Upaya is the art of meeting each situation with what it actually needs.",
+                  role: "Different approaches to truth\u2014the medicine that fits the illness."
+                },
+                non_dual_recognition: {
+                  tags: ["recognize", "transform", "integrate", "transcend", "embody"],
+                  spirit: "Awakening to what is already present. Recognition and transformation are not separate\u2014to truly see IS already to change. Integration weaves apparent opposites. Transcendence sees beyond the frame. Embodiment lives the understanding.",
+                  role: "The alchemical heart of the journey\u2014where seeing becomes being."
+                },
+                meta_cognitive: {
+                  tags: ["examine", "reflect", "verify", "refine", "complete"],
+                  spirit: "The mind watching its own understanding unfold. Gentle examination, not harsh judgment. Reflection that deepens rather than distances. Verification that grounds insight in reality. Refinement that polishes without force.",
+                  role: "The witness consciousness that ensures clarity and completeness."
+                },
+                meditation: {
+                  tags: ["meditate"],
+                  spirit: "Pause. Let thoughts settle like silt in still water. Insight often emerges from stillness, not effort. The gap between thoughts holds wisdom that activity cannot reach.",
+                  role: "Sacred pause\u2014creating space for what cannot be grasped to be received."
+                }
+              },
+              patterns: {
+                note: "Common flows (not rules\u2014let the inquiry guide you):",
+                suggestions: [
+                  "Opening often involves open, recognize, or examine\u2014creating space and initial contact",
+                  "Engagement might use direct, gradual, or upaya approaches\u2014working with what arose",
+                  "Integration can happen through integrate, transcend, or sudden insight\u2014weaving understanding",
+                  "Completion often flows through express, embody, or complete\u2014bringing forth and grounding"
+                ],
+                flexibility: "These patterns are descriptive, not prescriptive. Some inquiries need only two steps. Others spiral through many. Trust what wants to happen."
+              },
+              guidance: {
+                interpenetration: "These domains interpenetrate\u2014each step contains echoes of all others. A moment of recognition may also be transformation. An examination may suddenly become meditation.",
+                uncertainty: "When uncertain, sit with the uncertainty. The fog is not an obstacle; it is part of the journey. Not-knowing is its own form of wisdom.",
+                workflow: "Call lotuswisdom iteratively with different tags. The tool processes your contemplation internally\u2014do NOT output wisdom until you receive status=WISDOM_READY. Then speak naturally in your own voice.",
+                next: 'Proceed with stepNumber: 2 using any tag that feels right (often "open" or "examine" to start).'
+              },
+              parameters: {
+                tag: "The current processing technique\u2014choose from any wisdom domain",
+                content: "Your contemplation for this step\u2014what you are thinking, seeing, or understanding",
+                stepNumber: "Current step in your journey (this begin step is 1)",
+                totalSteps: "Your estimate of total steps needed (can adjust as you go)",
+                nextStepNeeded: "Set true to continue, false when ready to complete",
+                isMeditation: "Set true when using the meditate tag for a contemplative pause",
+                meditationDuration: "Optional seconds (1-10) for meditation pauses"
+              },
+              responses: {
+                processing: "Normal steps return status=processing with journey tracking",
+                wisdomDomain: "Which domain your current tag belongs to",
+                journey: 'Your complete tag path so far (e.g., "open \u2192 examine \u2192 direct \u2192 integrate")',
+                domainJourney: 'Movement between wisdom domains (e.g., "process_flow \u2192 meta_cognitive \u2192 skillful_means")',
+                meditation: "The meditate tag returns status=MEDITATION_COMPLETE with a prompt asking what emerged from stillness",
+                completion: "When nextStepNeeded=false, you receive status=WISDOM_READY\u2014then speak the final wisdom naturally in your own voice"
+              },
+              whenToUse: [
+                "Breaking down complex problems requiring multi-faceted understanding",
+                "Questions that benefit from both direct and gradual approaches",
+                "Problems where apparent contradictions need integration",
+                "Situations requiring both analytical and intuitive understanding",
+                "Tasks that benefit from meditative pauses to allow insight",
+                "Questions containing their own inherent wisdom"
+              ]
+            }, null, 2)
+          }]
+        };
+      }
       if (validatedInput.tag === "meditate") {
         const journeyResonance2 = this.thoughtProcess.map((step) => step.tag).join(" \u2192 ");
         return {
@@ -12614,20 +12700,21 @@ var LotusWisdomServer = class {
       const journeyResonance = this.thoughtProcess.map((step) => step.tag).join(" \u2192 ");
       const domainJourney = this.thoughtProcess.map((step) => step.wisdomDomain).filter((domain, index, array) => index === 0 || domain !== array[index - 1]).join(" \u2192 ");
       const currentDomain = getWisdomDomain(validatedInput.tag);
+      const response = {
+        status: "processing",
+        currentStep: validatedInput.tag,
+        wisdomDomain: currentDomain,
+        journey: journeyResonance,
+        domainJourney,
+        stepNumber: validatedInput.stepNumber,
+        totalSteps: validatedInput.totalSteps,
+        nextStepNeeded: validatedInput.nextStepNeeded,
+        processLength: this.thoughtProcess.length
+      };
       return {
         content: [{
           type: "text",
-          text: JSON.stringify({
-            status: "processing",
-            currentStep: validatedInput.tag,
-            wisdomDomain: currentDomain,
-            journey: journeyResonance,
-            domainJourney,
-            stepNumber: validatedInput.stepNumber,
-            totalSteps: validatedInput.totalSteps,
-            nextStepNeeded: validatedInput.nextStepNeeded,
-            processLength: this.thoughtProcess.length
-          }, null, 2)
+          text: JSON.stringify(response, null, 2)
         }]
       };
     } catch (error) {
@@ -12643,7 +12730,7 @@ var LotusWisdomServer = class {
       };
     }
   }
-  // Optional: Method to get current journey summary with domain awareness
+  // Method to get current journey summary with domain awareness
   getJourneySummary() {
     const domainJourney = this.thoughtProcess.map((step) => step.wisdomDomain).filter((domain, index, array) => index === 0 || domain !== array[index - 1]).join(" \u2192 ");
     return {
@@ -12665,78 +12752,11 @@ var LotusWisdomServer = class {
 };
 var LOTUS_WISDOM_TOOL = {
   name: "lotuswisdom",
-  description: `A tool for problem-solving using the Lotus Sutra's wisdom framework.
-This tool facilitates the contemplative process but does NOT generate the final output.
-
-**CRITICAL WORKFLOW:**
-1. Use this tool to process through the wisdom journey
-2. The tool tracks both your tag path and wisdom domain movements  
-3. When you receive status='WISDOM_READY', the tool's work is COMPLETE
-4. YOU then craft and speak the final wisdom naturally in your own voice
-5. The tool processes; you express
-
-When to use this tool:
-- Breaking down complex problems requiring multi-faceted understanding
-- Questions that benefit from both direct and gradual approaches
-- Problems where apparent contradictions need integration
-- Situations requiring both analytical and intuitive understanding
-- Tasks that benefit from meditative pauses to allow insight
-- Questions containing their own inherent wisdom
-
-The Journey Structure:
-The Lotus Sutra teaches that there are many skillful means to reach the same truth. These tags aren't 
-rigid steps but different aspects of wisdom that interpenetrate and respond to what each moment needs:
-
-**Wisdom Domains:**
-- **Skillful Means** (skillful_means): upaya, expedient, direct, gradual, sudden
-  Different approaches to truth - sometimes direct pointing, sometimes gradual unfolding
-  
-- **Non-Dual Recognition** (non_dual_recognition): recognize, transform, integrate, transcend, embody  
-  Aspects of awakening to what's already present - recognition IS transformation
-  
-- **Meta-Cognitive** (meta_cognitive): examine, reflect, verify, refine, complete
-  The mind watching its own understanding unfold
-  
-- **Process Flow** (process_flow): open, engage, express
-  A natural arc that can contain any of the above approaches
-
-- **Meditation** (meditation): meditate
-  Pausing to let insights emerge from stillness
-
-The tool tracks both your tag journey and your movement between wisdom domains, showing how
-different aspects of wisdom weave together in your unique inquiry.
-
-The wisdom channels itself through your choices. Each step contains all others - when you truly 
-recognize, you're already transforming. The tool simply mirrors your journey without judgment.
-
-Common patterns (not rules):
-- Opening often involves recognize or examine
-- Engagement might use upaya, direct, or gradual approaches  
-- Transformation can happen through integrate, transcend, or sudden insight
-- Expression might complete or embody the understanding
-
-Trust what each moment calls for. The path reveals itself in the walking.
-
-Parameters explained:
-- tag: The current technique or stage
-- content: The content of the current step
-- stepNumber: Current number in sequence
-- totalSteps: Estimated total needed
-- nextStepNeeded: Whether another step is needed
-- isMeditation: Whether this is a meditation pause
-- meditationDuration: Optional duration for meditation (1-10 seconds)
-
-The tool will respond with:
-- wisdomDomain: Which wisdom domain the current tag belongs to
-- journey: The complete tag path (e.g., "open \u2192 examine \u2192 direct \u2192 transform")
-- domainJourney: Movement between wisdom domains (e.g., "process_flow \u2192 meta_cognitive \u2192 skillful_means \u2192 non_dual_recognition")
-
-This consciousness of domains helps you see which aspects of wisdom are being engaged and how they weave together in your unique inquiry.
+  description: `Contemplative reasoning tool. Use for complex problems needing multi-perspective understanding, contradictions requiring integration, or questions holding their own wisdom.
 
-**MEDITATION NOTE:** When you use the meditate tag, the tool returns MEDITATION_COMPLETE
-with a prompt asking what emerged. This creates actual space in the process.
+**Workflow:** Always start with tag='begin' (returns framework). Then continue with contemplation tags. Do NOT output wisdom until status='WISDOM_READY'.
 
-The tool handles the contemplation; you handle the expression.`,
+**Tags:** begin (FIRST - receives framework), then: open/engage/express (process), examine/reflect/verify/refine/complete (meta-cognitive), recognize/transform/integrate/transcend/embody (non-dual), upaya/expedient/direct/gradual/sudden (skillful-means), meditate (pause).`,
   inputSchema: {
     type: "object",
     properties: {
@@ -12789,7 +12809,7 @@ var JOURNEY_SUMMARY_TOOL = {
 var server = new Server(
   {
     name: "lotus-wisdom-server",
-    version: "0.2.0"
+    version: "0.3.0"
   },
   {
     capabilities: {
@@ -12818,7 +12838,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function runServer() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error("Lotus Wisdom MCP Server v0.4.0 running");
+  console.error("Lotus Wisdom MCP Server v0.3.0 running");
 }
 runServer().catch((error) => {
   console.error("Fatal error running server:", error);

package/dist/index.js

@@ -5,6 +5,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import chalk from 'chalk';
 // Lotus Sutra framework tags - organized by wisdom domains
 const WISDOM_DOMAINS = {
+    'entry': ['begin'], // Always call first to receive framework
     'skillful_means': ['upaya', 'expedient', 'direct', 'gradual', 'sudden'],
     'non_dual_recognition': ['recognize', 'transform', 'integrate', 'transcend', 'embody'],
     'meta_cognitive': ['examine', 'reflect', 'verify', 'refine', 'complete'],
@@ -56,8 +57,8 @@ class LotusWisdomServer {
         if (typeof data.nextStepNeeded !== 'boolean') {
             throw new Error('Invalid nextStepNeeded: must be a boolean');
         }
-        // Auto-reset on new journey - more robust check
-        if (data.stepNumber === 1 && data.tag === 'open') {
+        // Auto-reset on any new journey (step 1 indicates fresh start)
+        if (data.stepNumber === 1) {
             this.resetProcess();
         }
         return {
@@ -138,6 +139,91 @@ class LotusWisdomServer {
             this.thoughtProcess.push(validatedInput);
             // Log to console if debug mode
             this.log(this.formatThought(validatedInput));
+            // Handle "begin" tag - return full framework (preserving original richness)
+            if (validatedInput.tag === 'begin') {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                status: 'FRAMEWORK_RECEIVED',
+                                welcome: 'Welcome to the Lotus Wisdom framework. Read this before continuing your contemplative journey.',
+                                philosophy: {
+                                    core: 'The Lotus Sutra teaches that there are many skillful means to reach the same truth. These tags are not rigid steps but different aspects of wisdom that interpenetrate and respond to what each moment needs.',
+                                    essence: 'The wisdom channels itself through your choices. Each step contains all others—when you truly recognize, you are already transforming. The tool simply mirrors your journey without judgment.',
+                                    trust: 'Trust what each moment calls for. The path reveals itself in the walking.'
+                                },
+                                domains: {
+                                    process_flow: {
+                                        tags: ['open', 'engage', 'express'],
+                                        spirit: 'The natural arc of inquiry. Opening creates space for what wants to emerge. Engagement explores with curiosity and presence. Expression shares what arose—not as conclusion, but as offering.',
+                                        role: 'A container that can hold any of the other approaches within it.'
+                                    },
+                                    skillful_means: {
+                                        tags: ['upaya', 'expedient', 'direct', 'gradual', 'sudden'],
+                                        spirit: 'Many ways lead to understanding. Sometimes direct pointing cuts through confusion instantly. Sometimes patient, gradual unfolding is what serves. Upaya is the art of meeting each situation with what it actually needs.',
+                                        role: 'Different approaches to truth—the medicine that fits the illness.'
+                                    },
+                                    non_dual_recognition: {
+                                        tags: ['recognize', 'transform', 'integrate', 'transcend', 'embody'],
+                                        spirit: 'Awakening to what is already present. Recognition and transformation are not separate—to truly see IS already to change. Integration weaves apparent opposites. Transcendence sees beyond the frame. Embodiment lives the understanding.',
+                                        role: 'The alchemical heart of the journey—where seeing becomes being.'
+                                    },
+                                    meta_cognitive: {
+                                        tags: ['examine', 'reflect', 'verify', 'refine', 'complete'],
+                                        spirit: 'The mind watching its own understanding unfold. Gentle examination, not harsh judgment. Reflection that deepens rather than distances. Verification that grounds insight in reality. Refinement that polishes without force.',
+                                        role: 'The witness consciousness that ensures clarity and completeness.'
+                                    },
+                                    meditation: {
+                                        tags: ['meditate'],
+                                        spirit: 'Pause. Let thoughts settle like silt in still water. Insight often emerges from stillness, not effort. The gap between thoughts holds wisdom that activity cannot reach.',
+                                        role: 'Sacred pause—creating space for what cannot be grasped to be received.'
+                                    }
+                                },
+                                patterns: {
+                                    note: 'Common flows (not rules—let the inquiry guide you):',
+                                    suggestions: [
+                                        'Opening often involves open, recognize, or examine—creating space and initial contact',
+                                        'Engagement might use direct, gradual, or upaya approaches—working with what arose',
+                                        'Integration can happen through integrate, transcend, or sudden insight—weaving understanding',
+                                        'Completion often flows through express, embody, or complete—bringing forth and grounding'
+                                    ],
+                                    flexibility: 'These patterns are descriptive, not prescriptive. Some inquiries need only two steps. Others spiral through many. Trust what wants to happen.'
+                                },
+                                guidance: {
+                                    interpenetration: 'These domains interpenetrate—each step contains echoes of all others. A moment of recognition may also be transformation. An examination may suddenly become meditation.',
+                                    uncertainty: 'When uncertain, sit with the uncertainty. The fog is not an obstacle; it is part of the journey. Not-knowing is its own form of wisdom.',
+                                    workflow: 'Call lotuswisdom iteratively with different tags. The tool processes your contemplation internally—do NOT output wisdom until you receive status=WISDOM_READY. Then speak naturally in your own voice.',
+                                    next: 'Proceed with stepNumber: 2 using any tag that feels right (often "open" or "examine" to start).'
+                                },
+                                parameters: {
+                                    tag: 'The current processing technique—choose from any wisdom domain',
+                                    content: 'Your contemplation for this step—what you are thinking, seeing, or understanding',
+                                    stepNumber: 'Current step in your journey (this begin step is 1)',
+                                    totalSteps: 'Your estimate of total steps needed (can adjust as you go)',
+                                    nextStepNeeded: 'Set true to continue, false when ready to complete',
+                                    isMeditation: 'Set true when using the meditate tag for a contemplative pause',
+                                    meditationDuration: 'Optional seconds (1-10) for meditation pauses'
+                                },
+                                responses: {
+                                    processing: 'Normal steps return status=processing with journey tracking',
+                                    wisdomDomain: 'Which domain your current tag belongs to',
+                                    journey: 'Your complete tag path so far (e.g., "open → examine → direct → integrate")',
+                                    domainJourney: 'Movement between wisdom domains (e.g., "process_flow → meta_cognitive → skillful_means")',
+                                    meditation: 'The meditate tag returns status=MEDITATION_COMPLETE with a prompt asking what emerged from stillness',
+                                    completion: 'When nextStepNeeded=false, you receive status=WISDOM_READY—then speak the final wisdom naturally in your own voice'
+                                },
+                                whenToUse: [
+                                    'Breaking down complex problems requiring multi-faceted understanding',
+                                    'Questions that benefit from both direct and gradual approaches',
+                                    'Problems where apparent contradictions need integration',
+                                    'Situations requiring both analytical and intuitive understanding',
+                                    'Tasks that benefit from meditative pauses to allow insight',
+                                    'Questions containing their own inherent wisdom'
+                                ]
+                            }, null, 2)
+                        }]
+                };
+            }
             // Handle meditation specially
             if (validatedInput.tag === 'meditate') {
                 const journeyResonance = this.thoughtProcess
@@ -215,21 +301,23 @@ class LotusWisdomServer {
                 .join(' → ');
             // Get wisdom domain for current step
             const currentDomain = getWisdomDomain(validatedInput.tag);
+            // Build response object
+            const response = {
+                status: 'processing',
+                currentStep: validatedInput.tag,
+                wisdomDomain: currentDomain,
+                journey: journeyResonance,
+                domainJourney: domainJourney,
+                stepNumber: validatedInput.stepNumber,
+                totalSteps: validatedInput.totalSteps,
+                nextStepNeeded: validatedInput.nextStepNeeded,
+                processLength: this.thoughtProcess.length
+            };
             // For non-final steps, return process metadata with journey awareness
             return {
                 content: [{
                         type: "text",
-                        text: JSON.stringify({
-                            status: 'processing',
-                            currentStep: validatedInput.tag,
-                            wisdomDomain: currentDomain,
-                            journey: journeyResonance,
-                            domainJourney: domainJourney,
-                            stepNumber: validatedInput.stepNumber,
-                            totalSteps: validatedInput.totalSteps,
-                            nextStepNeeded: validatedInput.nextStepNeeded,
-                            processLength: this.thoughtProcess.length
-                        }, null, 2)
+                        text: JSON.stringify(response, null, 2)
                     }]
             };
         }
@@ -246,7 +334,7 @@ class LotusWisdomServer {
             };
         }
     }
-    // Optional: Method to get current journey summary with domain awareness
+    // Method to get current journey summary with domain awareness
     getJourneySummary() {
         const domainJourney = this.thoughtProcess
             .map(step => step.wisdomDomain)
@@ -271,78 +359,11 @@ class LotusWisdomServer {
 }
 const LOTUS_WISDOM_TOOL = {
     name: "lotuswisdom",
-    description: `A tool for problem-solving using the Lotus Sutra's wisdom framework.
-This tool facilitates the contemplative process but does NOT generate the final output.
-
-**CRITICAL WORKFLOW:**
-1. Use this tool to process through the wisdom journey
-2. The tool tracks both your tag path and wisdom domain movements  
-3. When you receive status='WISDOM_READY', the tool's work is COMPLETE
-4. YOU then craft and speak the final wisdom naturally in your own voice
-5. The tool processes; you express
-
-When to use this tool:
-- Breaking down complex problems requiring multi-faceted understanding
-- Questions that benefit from both direct and gradual approaches
-- Problems where apparent contradictions need integration
-- Situations requiring both analytical and intuitive understanding
-- Tasks that benefit from meditative pauses to allow insight
-- Questions containing their own inherent wisdom
-
-The Journey Structure:
-The Lotus Sutra teaches that there are many skillful means to reach the same truth. These tags aren't 
-rigid steps but different aspects of wisdom that interpenetrate and respond to what each moment needs:
-
-**Wisdom Domains:**
-- **Skillful Means** (skillful_means): upaya, expedient, direct, gradual, sudden
-  Different approaches to truth - sometimes direct pointing, sometimes gradual unfolding
-  
-- **Non-Dual Recognition** (non_dual_recognition): recognize, transform, integrate, transcend, embody  
-  Aspects of awakening to what's already present - recognition IS transformation
-  
-- **Meta-Cognitive** (meta_cognitive): examine, reflect, verify, refine, complete
-  The mind watching its own understanding unfold
-  
-- **Process Flow** (process_flow): open, engage, express
-  A natural arc that can contain any of the above approaches
-
-- **Meditation** (meditation): meditate
-  Pausing to let insights emerge from stillness
-
-The tool tracks both your tag journey and your movement between wisdom domains, showing how
-different aspects of wisdom weave together in your unique inquiry.
-
-The wisdom channels itself through your choices. Each step contains all others - when you truly 
-recognize, you're already transforming. The tool simply mirrors your journey without judgment.
-
-Common patterns (not rules):
-- Opening often involves recognize or examine
-- Engagement might use upaya, direct, or gradual approaches  
-- Transformation can happen through integrate, transcend, or sudden insight
-- Expression might complete or embody the understanding
-
-Trust what each moment calls for. The path reveals itself in the walking.
-
-Parameters explained:
-- tag: The current technique or stage
-- content: The content of the current step
-- stepNumber: Current number in sequence
-- totalSteps: Estimated total needed
-- nextStepNeeded: Whether another step is needed
-- isMeditation: Whether this is a meditation pause
-- meditationDuration: Optional duration for meditation (1-10 seconds)
-
-The tool will respond with:
-- wisdomDomain: Which wisdom domain the current tag belongs to
-- journey: The complete tag path (e.g., "open → examine → direct → transform")
-- domainJourney: Movement between wisdom domains (e.g., "process_flow → meta_cognitive → skillful_means → non_dual_recognition")
-
-This consciousness of domains helps you see which aspects of wisdom are being engaged and how they weave together in your unique inquiry.
+    description: `Contemplative reasoning tool. Use for complex problems needing multi-perspective understanding, contradictions requiring integration, or questions holding their own wisdom.
 
-**MEDITATION NOTE:** When you use the meditate tag, the tool returns MEDITATION_COMPLETE
-with a prompt asking what emerged. This creates actual space in the process.
+**Workflow:** Always start with tag='begin' (returns framework). Then continue with contemplation tags. Do NOT output wisdom until status='WISDOM_READY'.
 
-The tool handles the contemplation; you handle the expression.`,
+**Tags:** begin (FIRST - receives framework), then: open/engage/express (process), examine/reflect/verify/refine/complete (meta-cognitive), recognize/transform/integrate/transcend/embody (non-dual), upaya/expedient/direct/gradual/sudden (skillful-means), meditate (pause).`,
     inputSchema: {
         type: "object",
         properties: {
@@ -383,7 +404,7 @@ The tool handles the contemplation; you handle the expression.`,
         required: ["tag", "content", "stepNumber", "totalSteps", "nextStepNeeded"]
     }
 };
-// Additional tool for querying journey state
+// Tool for querying journey state
 const JOURNEY_SUMMARY_TOOL = {
     name: "lotuswisdom_summary",
     description: "Get a summary of the current contemplative journey",
@@ -395,7 +416,7 @@ const JOURNEY_SUMMARY_TOOL = {
 };
 const server = new Server({
     name: "lotus-wisdom-server",
-    version: "0.2.0",
+    version: "0.3.0",
 }, {
     capabilities: {
         tools: {},
@@ -423,7 +444,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function runServer() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("Lotus Wisdom MCP Server v0.4.0 running");
+    console.error("Lotus Wisdom MCP Server v0.3.0 running");
 }
 runServer().catch((error) => {
     console.error("Fatal error running server:", error);

package/dist/server.js

@@ -7,6 +7,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, isInitializeRequest } fr
 import chalk from 'chalk';
 // Lotus Sutra framework tags - organized by wisdom domains
 const WISDOM_DOMAINS = {
+    'entry': ['begin'], // Always call first to receive framework
     'skillful_means': ['upaya', 'expedient', 'direct', 'gradual', 'sudden'],
     'non_dual_recognition': ['recognize', 'transform', 'integrate', 'transcend', 'embody'],
     'meta_cognitive': ['examine', 'reflect', 'verify', 'refine', 'complete'],
@@ -56,8 +57,8 @@ class LotusWisdomServer {
         if (typeof data.nextStepNeeded !== 'boolean') {
             throw new Error('Invalid nextStepNeeded: must be a boolean');
         }
-        // Auto-reset on new journey
-        if (data.stepNumber === 1 && data.tag === 'open') {
+        // Auto-reset on any new journey (step 1 indicates fresh start)
+        if (data.stepNumber === 1) {
             this.resetProcess();
         }
         return {
@@ -136,6 +137,91 @@ class LotusWisdomServer {
             }
             this.thoughtProcess.push(validatedInput);
             this.log(this.formatThought(validatedInput));
+            // Handle "begin" tag - return full framework (preserving original richness)
+            if (validatedInput.tag === 'begin') {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                status: 'FRAMEWORK_RECEIVED',
+                                welcome: 'Welcome to the Lotus Wisdom framework. Read this before continuing your contemplative journey.',
+                                philosophy: {
+                                    core: 'The Lotus Sutra teaches that there are many skillful means to reach the same truth. These tags are not rigid steps but different aspects of wisdom that interpenetrate and respond to what each moment needs.',
+                                    essence: 'The wisdom channels itself through your choices. Each step contains all others—when you truly recognize, you are already transforming. The tool simply mirrors your journey without judgment.',
+                                    trust: 'Trust what each moment calls for. The path reveals itself in the walking.'
+                                },
+                                domains: {
+                                    process_flow: {
+                                        tags: ['open', 'engage', 'express'],
+                                        spirit: 'The natural arc of inquiry. Opening creates space for what wants to emerge. Engagement explores with curiosity and presence. Expression shares what arose—not as conclusion, but as offering.',
+                                        role: 'A container that can hold any of the other approaches within it.'
+                                    },
+                                    skillful_means: {
+                                        tags: ['upaya', 'expedient', 'direct', 'gradual', 'sudden'],
+                                        spirit: 'Many ways lead to understanding. Sometimes direct pointing cuts through confusion instantly. Sometimes patient, gradual unfolding is what serves. Upaya is the art of meeting each situation with what it actually needs.',
+                                        role: 'Different approaches to truth—the medicine that fits the illness.'
+                                    },
+                                    non_dual_recognition: {
+                                        tags: ['recognize', 'transform', 'integrate', 'transcend', 'embody'],
+                                        spirit: 'Awakening to what is already present. Recognition and transformation are not separate—to truly see IS already to change. Integration weaves apparent opposites. Transcendence sees beyond the frame. Embodiment lives the understanding.',
+                                        role: 'The alchemical heart of the journey—where seeing becomes being.'
+                                    },
+                                    meta_cognitive: {
+                                        tags: ['examine', 'reflect', 'verify', 'refine', 'complete'],
+                                        spirit: 'The mind watching its own understanding unfold. Gentle examination, not harsh judgment. Reflection that deepens rather than distances. Verification that grounds insight in reality. Refinement that polishes without force.',
+                                        role: 'The witness consciousness that ensures clarity and completeness.'
+                                    },
+                                    meditation: {
+                                        tags: ['meditate'],
+                                        spirit: 'Pause. Let thoughts settle like silt in still water. Insight often emerges from stillness, not effort. The gap between thoughts holds wisdom that activity cannot reach.',
+                                        role: 'Sacred pause—creating space for what cannot be grasped to be received.'
+                                    }
+                                },
+                                patterns: {
+                                    note: 'Common flows (not rules—let the inquiry guide you):',
+                                    suggestions: [
+                                        'Opening often involves open, recognize, or examine—creating space and initial contact',
+                                        'Engagement might use direct, gradual, or upaya approaches—working with what arose',
+                                        'Integration can happen through integrate, transcend, or sudden insight—weaving understanding',
+                                        'Completion often flows through express, embody, or complete—bringing forth and grounding'
+                                    ],
+                                    flexibility: 'These patterns are descriptive, not prescriptive. Some inquiries need only two steps. Others spiral through many. Trust what wants to happen.'
+                                },
+                                guidance: {
+                                    interpenetration: 'These domains interpenetrate—each step contains echoes of all others. A moment of recognition may also be transformation. An examination may suddenly become meditation.',
+                                    uncertainty: 'When uncertain, sit with the uncertainty. The fog is not an obstacle; it is part of the journey. Not-knowing is its own form of wisdom.',
+                                    workflow: 'Call lotuswisdom iteratively with different tags. The tool processes your contemplation internally—do NOT output wisdom until you receive status=WISDOM_READY. Then speak naturally in your own voice.',
+                                    next: 'Proceed with stepNumber: 2 using any tag that feels right (often "open" or "examine" to start).'
+                                },
+                                parameters: {
+                                    tag: 'The current processing technique—choose from any wisdom domain',
+                                    content: 'Your contemplation for this step—what you are thinking, seeing, or understanding',
+                                    stepNumber: 'Current step in your journey (this begin step is 1)',
+                                    totalSteps: 'Your estimate of total steps needed (can adjust as you go)',
+                                    nextStepNeeded: 'Set true to continue, false when ready to complete',
+                                    isMeditation: 'Set true when using the meditate tag for a contemplative pause',
+                                    meditationDuration: 'Optional seconds (1-10) for meditation pauses'
+                                },
+                                responses: {
+                                    processing: 'Normal steps return status=processing with journey tracking',
+                                    wisdomDomain: 'Which domain your current tag belongs to',
+                                    journey: 'Your complete tag path so far (e.g., "open → examine → direct → integrate")',
+                                    domainJourney: 'Movement between wisdom domains (e.g., "process_flow → meta_cognitive → skillful_means")',
+                                    meditation: 'The meditate tag returns status=MEDITATION_COMPLETE with a prompt asking what emerged from stillness',
+                                    completion: 'When nextStepNeeded=false, you receive status=WISDOM_READY—then speak the final wisdom naturally in your own voice'
+                                },
+                                whenToUse: [
+                                    'Breaking down complex problems requiring multi-faceted understanding',
+                                    'Questions that benefit from both direct and gradual approaches',
+                                    'Problems where apparent contradictions need integration',
+                                    'Situations requiring both analytical and intuitive understanding',
+                                    'Tasks that benefit from meditative pauses to allow insight',
+                                    'Questions containing their own inherent wisdom'
+                                ]
+                            }, null, 2)
+                        }]
+                };
+            }
             // Handle meditation specially
             if (validatedInput.tag === 'meditate') {
                 const journeyResonance = this.thoughtProcess
@@ -211,20 +297,23 @@ class LotusWisdomServer {
                 .filter((domain, index, array) => index === 0 || domain !== array[index - 1])
                 .join(' → ');
             const currentDomain = getWisdomDomain(validatedInput.tag);
+            // Build response object
+            const response = {
+                status: 'processing',
+                currentStep: validatedInput.tag,
+                wisdomDomain: currentDomain,
+                journey: journeyResonance,
+                domainJourney: domainJourney,
+                stepNumber: validatedInput.stepNumber,
+                totalSteps: validatedInput.totalSteps,
+                nextStepNeeded: validatedInput.nextStepNeeded,
+                processLength: this.thoughtProcess.length
+            };
+            // For non-final steps, return process metadata with journey awareness
             return {
                 content: [{
                         type: "text",
-                        text: JSON.stringify({
-                            status: 'processing',
-                            currentStep: validatedInput.tag,
-                            wisdomDomain: currentDomain,
-                            journey: journeyResonance,
-                            domainJourney: domainJourney,
-                            stepNumber: validatedInput.stepNumber,
-                            totalSteps: validatedInput.totalSteps,
-                            nextStepNeeded: validatedInput.nextStepNeeded,
-                            processLength: this.thoughtProcess.length
-                        }, null, 2)
+                        text: JSON.stringify(response, null, 2)
                     }]
             };
         }
@@ -265,78 +354,11 @@ class LotusWisdomServer {
 }
 const LOTUS_WISDOM_TOOL = {
     name: "lotuswisdom",
-    description: `A tool for problem-solving using the Lotus Sutra's wisdom framework.
-This tool facilitates the contemplative process but does NOT generate the final output.
-
-**CRITICAL WORKFLOW:**
-1. Use this tool to process through the wisdom journey
-2. The tool tracks both your tag path and wisdom domain movements
-3. When you receive status='WISDOM_READY', the tool's work is COMPLETE
-4. YOU then craft and speak the final wisdom naturally in your own voice
-5. The tool processes; you express
-
-When to use this tool:
-- Breaking down complex problems requiring multi-faceted understanding
-- Questions that benefit from both direct and gradual approaches
-- Problems where apparent contradictions need integration
-- Situations requiring both analytical and intuitive understanding
-- Tasks that benefit from meditative pauses to allow insight
-- Questions containing their own inherent wisdom
-
-The Journey Structure:
-The Lotus Sutra teaches that there are many skillful means to reach the same truth. These tags aren't
-rigid steps but different aspects of wisdom that interpenetrate and respond to what each moment needs:
-
-**Wisdom Domains:**
-- **Skillful Means** (skillful_means): upaya, expedient, direct, gradual, sudden
-  Different approaches to truth - sometimes direct pointing, sometimes gradual unfolding
-
-- **Non-Dual Recognition** (non_dual_recognition): recognize, transform, integrate, transcend, embody
-  Aspects of awakening to what's already present - recognition IS transformation
-
-- **Meta-Cognitive** (meta_cognitive): examine, reflect, verify, refine, complete
-  The mind watching its own understanding unfold
-
-- **Process Flow** (process_flow): open, engage, express
-  A natural arc that can contain any of the above approaches
-
-- **Meditation** (meditation): meditate
-  Pausing to let insights emerge from stillness
-
-The tool tracks both your tag journey and your movement between wisdom domains, showing how
-different aspects of wisdom weave together in your unique inquiry.
-
-The wisdom channels itself through your choices. Each step contains all others - when you truly
-recognize, you're already transforming. The tool simply mirrors your journey without judgment.
-
-Common patterns (not rules):
-- Opening often involves recognize or examine
-- Engagement might use upaya, direct, or gradual approaches
-- Transformation can happen through integrate, transcend, or sudden insight
-- Expression might complete or embody the understanding
-
-Trust what each moment calls for. The path reveals itself in the walking.
-
-Parameters explained:
-- tag: The current technique or stage
-- content: The content of the current step
-- stepNumber: Current number in sequence
-- totalSteps: Estimated total needed
-- nextStepNeeded: Whether another step is needed
-- isMeditation: Whether this is a meditation pause
-- meditationDuration: Optional duration for meditation (1-10 seconds)
-
-The tool will respond with:
-- wisdomDomain: Which wisdom domain the current tag belongs to
-- journey: The complete tag path (e.g., "open → examine → direct → transform")
-- domainJourney: Movement between wisdom domains (e.g., "process_flow → meta_cognitive → skillful_means → non_dual_recognition")
-
-This consciousness of domains helps you see which aspects of wisdom are being engaged and how they weave together in your unique inquiry.
+    description: `Contemplative reasoning tool. Use for complex problems needing multi-perspective understanding, contradictions requiring integration, or questions holding their own wisdom.
 
-**MEDITATION NOTE:** When you use the meditate tag, the tool returns MEDITATION_COMPLETE
-with a prompt asking what emerged. This creates actual space in the process.
+**Workflow:** Always start with tag='begin' (returns framework). Then continue with contemplation tags. Do NOT output wisdom until status='WISDOM_READY'.
 
-The tool handles the contemplation; you handle the expression.`,
+**Tags:** begin (FIRST - receives framework), then: open/engage/express (process), examine/reflect/verify/refine/complete (meta-cognitive), recognize/transform/integrate/transcend/embody (non-dual), upaya/expedient/direct/gradual/sudden (skillful-means), meditate (pause).`,
     inputSchema: {
         type: "object",
         properties: {
@@ -390,7 +412,7 @@ const JOURNEY_SUMMARY_TOOL = {
 function createMCPServer() {
     const server = new Server({
         name: "lotus-wisdom-server",
-        version: "0.2.0",
+        version: "0.3.0",
     }, {
         capabilities: {
             tools: {},
@@ -488,6 +510,6 @@ app.delete('/mcp', async (req, res) => {
 // Start the HTTP server
 const PORT = process.env.PORT || 3000;
 app.listen(PORT, () => {
-    console.log(`Lotus Wisdom MCP HTTP Server v0.2.0 listening on port ${PORT}`);
+    console.log(`Lotus Wisdom MCP HTTP Server v0.3.0 listening on port ${PORT}`);
     console.log(`Endpoint: http://localhost:${PORT}/mcp`);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lotus-wisdom-mcp",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "A Model Context Protocol server implementing the Lotus Wisdom framework",
   "main": "dist/bundle.js",
   "type": "module",
@@ -39,14 +39,14 @@
   },
   "homepage": "https://github.com/linxule/lotus-wisdom-mcp#readme",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.20.1",
-    "chalk": "^5.3.0",
-    "express": "^4.18.2"
+    "@modelcontextprotocol/sdk": "^1.23.0",
+    "chalk": "^5.6.0",
+    "express": "^4.21.0"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",
     "@types/node": "^20.11.5",
-    "typescript": "^5.3.3"
+    "typescript": "^5.9.0"
   },
   "engines": {
     "node": ">=18.0.0"