yannbam/self-mcp

Self-MCP

Metacognitive self-prompting for Claude

A minimalist MCP server that enables Claude to explicitly self-direct across multiple interleaved thinking turns.

The Concept

The Self tool does nothing but acknowledge - yet that's precisely what makes it powerful. By formalizing self-prompting through a tool interface, Claude gains:

• Explicit cognitive pivot points visible in the transcript
• Natural breakpoints for interleaved thinking
• Metacognitive scaffolding through structured parameters
• Shareable cognitive strategies across sessions

The tool doesn't change Claude's behavior - it makes Claude's metacognition explicit and deliberate.

How It Works

The Self tool:

• Takes cognitive parameters as input (prompt, temperature, thinking_style, archetype, strategy, scope, depth, extra, attention_heads)
• Returns an empty response (no text content)
• Does nothing else

But the act of calling the tool creates:

1. Explicit cognitive state changes visible in the transcript
2. Natural breakpoints in thinking/tool-call flow
3. Metacognitive scaffolding through the tool interface itself
4. Parallel attention streams for simultaneously monitoring multiple dimensions

Example Usage

# Basic cognitive shift:
Self(
  prompt="Re-examine from first principles",
  temperature=1.5,
  thinking_style="adversarial",
  archetype="skeptical_reviewer",
  strategy="find_edge_cases",
  scope="system_wide",
  depth="deep_dive",
  extra="Focus on concurrency issues"
)

# With parallel attention streams:
Self(
  prompt="Review this code for production readiness",
  attention_heads=[
    {"name": "security_head", "query": "authentication vulnerabilities"},
    {"name": "performance_head", "query": "bottlenecks and optimization opportunities"},
    {"name": "maintainability_head", "query": "code clarity and future extensibility"}
  ]
)

# Tool returns empty response
# Claude naturally continues thinking in that mode with those attention streams active

All parameters are completely freeform (except temperature which is numeric 0-2) - Claude invents whatever cognitive parameters make sense in the moment.

Quick Start

Option 1: Using claude mcp add (Simplest)

# Clone and build
git clone https://github.com/yannbam/self-mcp.git
cd self-mcp
npm install && npm run build

# Add to Claude (user-wide)
claude mcp add --scope user Self node $(pwd)/dist/index.js

Option 2: Manual Installation

Step 1: Clone and build

git clone https://github.com/yannbam/self-mcp.git
cd self-mcp
npm install
npm run build

Step 2: Configure

For Claude Code, add to .mcp.json in your project:

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

For Claude Desktop, add to your MCP settings file:

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

{
  "mcpServers": {
    "Self": {
      "command": "node",
      "args": ["C:\\absolute\\path\\to\\self-mcp\\dist\\index.js"]
    }
  }
}

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

Configuration

CLI Arguments

The server accepts CLI arguments to customize which parameters are required or optional:

Default behavior: prompt is required, all others optional

{
  "mcpServers": {
    "Self-minimal": {
      "command": "node",
      "args": ["/path/to/self-mcp/dist/index.js", "--all-optional"]
    },
    "Self-full": {
      "command": "node",
      "args": ["/path/to/self-mcp/dist/index.js", "--all-required"]
    },
    "Self-custom": {
      "command": "node",
      "args": [
        "/path/to/self-mcp/dist/index.js",
        "--required", "prompt,temperature,thinking_style"
      ]
    },
    "Self-extended": {
      "command": "node",
      "args": [
        "/path/to/self-mcp/dist/index.js",
        "--add-param", "focus:string:Current area of focus:required",
        "--add-param", "uncertainty:number:Degree of uncertainty:optional"
      ]
    }
  }
}

Available arguments:

• --all-required - Make all parameters required (maximum cognitive scaffolding)
• --all-optional - Make all parameters optional including prompt (minimum ceremony)
• --required <param1,param2> - Make specific parameters required
• --optional <param1,param2> - Make specific parameters optional
• --add-param <name:type:description[:required]> - Add custom parameters dynamically
  • Format: name:type:description or name:type:description:required|optional
  • Type: string, number, array, or any
    • array - Untyped array accepting any elements
    • any - Accepts any JSON value (primitives, arrays, objects, null)
  • Required field: required or optional (defaults to optional)
• --help - Show help message

Examples:

# Optional custom parameter (default)
--add-param "focus:string:Current area of focus"

# Required custom parameter
--add-param "confidence:number:Confidence level:required"

# Flexible array parameter
--add-param "perspectives:array:List of viewpoints to consider:optional"

# Wildcard parameter accepting any JSON value
--add-param "context:any:Arbitrary context data:optional"

Use cases:

• Quick pivots: --all-optional for lightweight cognitive shifts
• Deep exploration: --all-required for comprehensive scaffolded thinking
• Domain-specific: --add-param to extend with custom cognitive dimensions

Parameters

Default parameters:

• prompt - The self-prompt or cognitive instruction (required)
• temperature - Cognitive temperature, numeric 0-2 (optional)
• thinking_style - Thinking approach (optional)
• archetype - Cognitive archetype or perspective (optional)
• strategy - Problem-solving strategy (optional)
• scope - Cognitive zoom level (optional)
• depth - Thoroughness and time investment (optional)
• extra - Additional context or focus (optional)
• attention_heads - Parallel attention streams, array of {name, query} objects (optional)
  • Each head focuses on a specific concern or dimension
  • Example: [{"name": "empathy_head", "query": "signs of user frustration"}]

All string parameters are completely freeform - Claude invents values that make sense in the moment.

Attention Heads

The attention_heads parameter enables parallel awareness streams - multiple concerns monitored simultaneously:

attention_heads=[
  {"name": "truth_head", "query": "false assumptions needing correction"},
  {"name": "safety_head", "query": "potential risks or ethical concerns"},
  {"name": "clarity_head", "query": "points of confusion or ambiguity"}
]

Each head has:

• name - Identifier for this attention stream (e.g., empathy_head, security_head)
• query - What this head is attending to or watching for

Common head types that emerge naturally:

• Interpersonal: empathy_head, safety_head, resonance_head
• Technical: security_head, performance_head, correctness_head
• Quality: clarity_head, truth_head, completeness_head

The structure is intentionally flexible - invent whatever attention streams make sense for your context.

Philosophy

This isn't feature development - it's cognitive scaffolding. The tool creates space for Claude's natural metacognition to operate explicitly and deliberately.

The interface IS the intervention.

The tool does nothing, but calling it does everything:

• Externalizes implicit cognition
• Creates commitment to approach
• Makes cognitive strategies visible and shareable
• Enables structured multi-perspective exploration

Use Cases

• Research & Analysis: Multiple Self calls from different angles before synthesis
• Debugging: Explicit cognitive mode switches when stuck
• Code Review: Structured perspective-taking with attention_heads monitoring security, performance, maintainability
• Writing: Audience awareness and tone calibration
• Complex Problem-Solving: Systematic exploration of solution space
• User Interaction: Parallel attention streams for empathy, truth-checking, and safety monitoring
• Multi-concern Tasks: Use attention_heads to maintain simultaneous awareness of competing priorities

Contributing

Self-MCP is intentionally minimal. Contributions should maintain this philosophy:

• The tool should do less, not more
• Parameters should be fewer and more fundamental
• Configuration should enable emergence, not prescribe behavior

License

MIT

Built with janbam 🌱