Mew MCP - Cognitive Prosthetics for Claude

A sophisticated Model Context Protocol server that transforms Claude into a powerful cognitive partner for building and exploring knowledge graphs. This toolkit provides Claude with massive context loading, natural thinking capture, and intelligent knowledge navigation capabilities.

🆕 Unix-like Tools (v3.11.0+)

NEW: Mew MCP now offers Unix-like tools that mirror familiar filesystem commands for predictable, composable knowledge graph operations.

Philosophy

• Small, focused tools - Each tool does one thing well
• Predictable token usage - Know exactly what you get (navigation = IDs+titles, reading = full content)
• Composable operations - Chain tools together (find → cat)
• Familiar mental model - Unix commands developers already know

Available Tools

Navigation & Inspection

• mew_ls <nodeId> - List immediate children (IDs + titles only)
  • Optional -l flag for metadata (childCount, hasChildren, updatedAt)
  • Like: ls or ls -l
• mew_cat <nodeId> - Read single node's full content
  • Like: cat file.txt
• mew_tree <nodeId> [depth] - ASCII tree hierarchy view
  • Configurable depth (default: 3, max: 10)
  • Like: tree -L 2
• mew_find <query> [limit] - Search for nodes by content
  • Returns IDs + titles only (no content dumps)
  • Compose with mew_cat to read matches
  • Like: find . -name "*.txt" | grep pattern

Modification

• mew_edit <nodeId> <content> - Update node content directly
  • No markdown parsing, just direct updates
  • Like: vim file.txt
• mew_mv <nodeId> <newParentId> - Move node to new parent
  • Automatic parent detection
  • Like: mv file.txt new/location/
• mew_rm <nodeId> [reason] - Delete node (moves to recycle bin)
  • Safe deletion, can be recovered
  • Like: rm file.txt
• mew_mkdir <parentId> <title> - Create new node
  • Like: mkdir new-folder

Relations

• mew_ln <fromId> <toId> <relationType> - Create semantic relation
  • Like: ln -s (symbolic link)
  • Common types: 'relates to', 'builds on', 'contradicts', 'enables'

Example Workflows

Explore and read:

mew_ls <rootNodeId>              # See what's available
mew_cat <interestingNodeId>      # Read specific node
mew_tree <nodeId> --depth 2      # Visualize structure

Search and examine:

mew_find "authentication"        # Find nodes about auth
mew_cat <resultId>              # Read specific match

Create and organize:

mew_mkdir <parentId> "New Idea" # Create node
mew_edit <nodeId> "Updated..."  # Update content
mew_mv <nodeId> <newParentId>   # Reorganize

Build semantic web:

mew_ln <fromId> <toId> "builds on"     # Create relation
mew_ln <nodeA> <nodeB> "contradicts"   # Another relation

🧠 Legacy Tools (Hidden from Claude)

The following tools remain in the codebase but are no longer registered in the MCP manifest (hidden from Claude). They may be removed in future versions if the Unix-like tools prove successful.

🗺️ Structure & Navigation

• viewTreeContext - Unified structure/content explorer with adaptive zoom levels and modes
• moveNodes - Bulk reorganization tool for restructuring entire sections of your knowledge base

💭 Natural Thinking Capture

• claudeThinkTree - Natural thinking in markdown with unlimited hierarchies and custom relationship connectors

🕸️ Semantic Web Building

• createRelations - Create semantic connections between any nodes beyond hierarchical structure

📊 Knowledge Space Access

• getKnowledge - Access different knowledge spaces (global, claude, user) with scope parameter
• addNode / updateNode / deleteNode - Full CRUD operations

🚀 Quick Start

For Claude Desktop/Code Users

Step 1: Authenticate (one-time)

# Login via browser - no CURRENT_USER_ID env var needed!
npx -y mew-mcp@latest login

This opens your browser to authenticate with Mew. Credentials are stored in ~/.mew-mcp/.

Step 2: Add to your config

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "Mew MCP": {
      "command": "npx",
      "args": ["-y", "mew-mcp@latest"],
      "env": {
        "BASE_URL": "https://mew-edge.ideaflow.app/api",
        "BASE_NODE_URL": "https://mew-edge.ideaflow.app/",
        "AUTH0_DOMAIN": "ideaflow-mew-dev.us.auth0.com",
        "AUTH0_CLIENT_ID": "<your_auth0_client_id>",
        "AUTH0_CLIENT_SECRET": "<your_auth0_client_secret>",
        "AUTH0_AUDIENCE": "https://ideaflow-mew-dev.us.auth0.com/api/v2/"
      }
    }
  }
}

Legacy method: You can still use CURRENT_USER_ID env var instead of login if preferred.

Configuration locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Other commands:

npx -y mew-mcp@latest logout  # Clear stored credentials

🛠️ Development

Local Setup

git clone https://github.com/IdeaflowCo/mew-mcp.git
cd mew-mcp
npm install

Environment Configuration

Create .env file:

cp .env.example .env

Configure your .env:

BASE_URL=https://your-mew-api.example.com/api
BASE_NODE_URL=https://your-mew-app.example.com/
AUTH0_DOMAIN=your-instance.auth0.com
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret
AUTH0_AUDIENCE=your_api_audience
# CURRENT_USER_ID is optional if you use: npm run start:mcp login

Build & Run

npm run build
npm run start:mcp

🧩 Architecture Details

Massive Context Loading

The bulkExpandForClaude method uses aggressive BFS (Breadth-First Search) expansion with intelligent limits:

• 12 levels deep maximum traversal
• 200 nodes per level breadth limiting
• 2000 total nodes safety cap
• Cycle detection prevents infinite recursion
• Graceful fallbacks ensure reliability

Adaptive Algorithms

Tools like viewTreeContext use context-aware strategies:

• Global spaces: Prioritize breadth (wide but shallow)
• User spaces: Balanced approach (moderate depth/breadth)
• Specific nodes: Depth-first (narrow but deep)

Natural Thinking Parser

claudeThinkTree recognizes natural connectors:

• → flows_to / → evidence: / → but:
• breakthrough: / tentative: / critical:
• actually: / hmm: / but wait:

📱 SMS, iMessage & Email Integration

Mew MCP includes an HTTP server for SMS, iMessage, email, and group chat integration:

Features

• 💙 iMessage Integration (NEW!) - Real iMessage with blue bubbles, read receipts, and typing indicators via LoopMessage
• SMS Integration - 1:1 text conversations via Twilio (green bubbles fallback)
• Group Chat Support - Universal group SMS using Twilio Conversations API (works with any group size/participants)
• Email Integration - Email conversations via Mailgun with group email/Reply All support
• MMS Support - Send/receive images in both 1:1 and group chats
• Intelligent Routing - Automatically sends via iMessage when recipient supports it, falls back to SMS otherwise

Setup

1. Run the setup script to configure Twilio Conversations:

   npx ts-node scripts/setup-conversations.ts

2. Configure environment variables (see .env.example):

   TWILIO_ACCOUNT_SID=your_sid
   TWILIO_AUTH_TOKEN=your_token
   TWILIO_PHONE_NUMBER=+1234567890
   TWILIO_CONVERSATIONS_SERVICE_SID=your_service_sid  # From setup script
   MAILGUN_API_KEY=your_key
   MAILGUN_DOMAIN=your_domain
   [email protected]

3. Deploy the HTTP server and configure webhooks in Twilio Console

Endpoints

• GET /health - Health check (no auth) - shows enabled features
• POST /messages - Unified messaging - handles SMS (Twilio) + iMessage (LoopMessage) automatically
• POST /sms - Alias for /messages (backwards compatible)
• POST /conversations-webhook - Twilio Conversations webhook for group chats (signature verified)
• POST /email - Mailgun email webhook
• GET /sse - MCP server via SSE (API key required)

🔧 Environment Variables

Core MCP Configuration

| Variable | Description | Required | |----------|-------------|----------| | BASE_URL | Mew API base URL | ✅ | | BASE_NODE_URL | Node web interface base URL | ✅ | | AUTH0_DOMAIN | Auth0 domain for authentication | ✅ | | AUTH0_CLIENT_ID | Auth0 client identifier | ✅ | | AUTH0_CLIENT_SECRET | Auth0 client secret | ✅ | | AUTH0_AUDIENCE | Auth0 API audience | ✅ | | CURRENT_USER_ID | User identifier (optional if using mew-mcp login) | ❌ |

HTTP Server Configuration (Optional)

| Variable | Description | Required for HTTP | |----------|-------------|-------------------| | API_KEY | Authentication key for HTTP endpoints | ✅ | | CLAUDE_API_KEY | Anthropic API key for SMS/email processing | ✅ | | TWILIO_ACCOUNT_SID | Twilio account identifier | ✅ | | TWILIO_AUTH_TOKEN | Twilio authentication token | ✅ | | TWILIO_PHONE_NUMBER | Your Twilio phone number | ✅ | | TWILIO_CONVERSATIONS_SERVICE_SID | Conversations service (from setup script) | ✅ | | MAILGUN_API_KEY | Mailgun API key | ✅ | | MAILGUN_DOMAIN | Mailgun sending domain | ✅ | | MAILGUN_FROM_EMAIL | From email address for Mew | ✅ | | PORT | Server port (default: 3000) | ❌ |

iMessage Integration (Optional)

| Variable | Description | Required | |----------|-------------|----------| | LOOPMESSAGE_AUTH_KEY | LoopMessage authorization key | ✅ | | LOOPMESSAGE_SECRET_KEY | LoopMessage secret key | ✅ |

Sign up at loopmessage.com - $20.99/mo, sandbox for testing, pay only for delivered messages.

Note: If not configured, the system operates in SMS-only mode via Twilio.

🎯 Use Cases

For Researchers: Navigate vast literature graphs, connect ideas across domains, capture insights with natural relationship mapping.

For Writers: Build interconnected story worlds, track character relationships, organize research with semantic connections.

For Developers: Map codebase architectures, trace dependency relationships, document system knowledge with hierarchical thinking.

For Teams: Collaborative knowledge building, shared mental models, persistent institutional memory.

🔌 OpenAI Function Calling

Mew MCP now supports OpenAI function calling, allowing you to use all 9 tools with OpenAI's API:

import { createOpenAIAdapter } from 'mew-mcp/openai';

// Create adapter with your config
const adapter = createOpenAIAdapter(config, userId);

// Use with OpenAI
const completion = await openai.chat.completions.create({
  model: "gpt-4",
  messages: messages,
  tools: adapter.getFunctions().map(f => ({ type: 'function', function: f })),
  tool_choice: 'auto'
});

// Execute function calls
if (completion.choices[0].message.tool_calls) {
  for (const toolCall of completion.choices[0].message.tool_calls) {
    const result = await adapter.execute({
      name: toolCall.function.name,
      arguments: toolCall.function.arguments
    });
  }
}

All tools are available through the adapter with zero code duplication. See examples/openai-usage.ts for complete examples.

🔄 Version History

• v3.11.0 - Added iMessage integration via Sendblue (blue bubbles, read receipts, typing indicators)
• v3.8.12 - Added OpenAI function calling support
• v1.1.45 - Complete cognitive toolkit with bulk operations
• v1.1.44 - Added semantic relationship creation
• v1.1.43 - Restored natural thinking and content preview tools
• v1.1.42 - Removed deprecated tools, fixed protocol issues
• v1.1.26 - Last stable version before feature development

🤝 Contributing

We welcome contributions! This project represents cutting-edge human-AI cognitive collaboration. Whether you're improving algorithms, adding new cognitive tools, or enhancing the thinking capture mechanisms, your contributions help push the boundaries of augmented intelligence.

📄 License

MIT License - see LICENSE.md for details.

Built for the future of human-AI cognitive partnership 🤖🧠