serena-slim 0.0.1-slim.1

package/README.md

@@ -0,0 +1,184 @@
+# serena-slim
+
+> **Serena MCP server optimized for AI assistants** — Reduce context window tokens by 51.2% while keeping full functionality. Compatible with Claude, ChatGPT, Gemini, Cursor, and all MCP clients.
+
+[![npm version](https://img.shields.io/npm/v/serena-slim.svg)](https://www.npmjs.com/package/serena-slim)
+[![Test Status](https://img.shields.io/badge/tests-passing-brightgreen)](https://github.com/mcpslim/mcpslim)
+[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
+
+## What is serena-slim?
+
+A **token-optimized** version of the Serena [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server.
+
+### The Problem
+
+MCP tool schemas consume significant **context window tokens**. When AI assistants like Claude or ChatGPT load MCP tools, each tool definition takes up valuable context space.
+
+The original `serena` loads **29 tools** consuming approximately **~23,878 tokens** — that's space you could use for actual conversation.
+
+### The Solution
+
+`serena-slim` intelligently **groups 29 tools into 18 semantic operations**, reducing token usage by **51.2%** — with **zero functionality loss**.
+
+Your AI assistant sees fewer, smarter tools. Every original capability remains available.
+
+## Performance
+
+| Metric | Original | Slim | Reduction |
+|--------|----------|------|-----------|
+| Tools | 29 | 18 | **-38%** |
+| Schema Tokens | 7,348 | 1,395 | **81.0%** |
+| Claude Code (est.) | ~23,878 | ~11,655 | **~51.2%** |
+
+> **Benchmark Info**
+> - Original: `serena@0.0.1`
+> - Schema tokens measured with [tiktoken](https://github.com/openai/tiktoken) (cl100k_base)
+> - Claude Code estimate includes ~570 tokens/tool overhead
+
+## Quick Start
+
+### One-Command Setup (Recommended)
+
+```bash
+# Claude Desktop - auto-configure
+npx serena-slim --setup claude
+
+# Cursor - auto-configure
+npx serena-slim --setup cursor
+
+# Interactive mode (choose your client)
+npx serena-slim --setup
+```
+
+Done! Restart your app to use serena.
+
+### CLI Tools (already have CLI?)
+
+```bash
+# Claude Code
+claude mcp add serena -- npx -y serena-slim
+
+# VS Code (Copilot, Cline, Roo Code)
+code --add-mcp '{"name":"serena","command":"npx","args":["-y","serena-slim"]}'
+```
+
+## Manual Setup
+
+<details>
+<summary>Click to expand manual configuration options</summary>
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+| OS | Path |
+|----|------|
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+
+```json
+{
+  "mcpServers": {
+    "serena": {
+      "command": "npx",
+      "args": ["-y", "serena-slim"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` (global) or `<project>/.cursor/mcp.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "serena": {
+      "command": "npx",
+      "args": ["-y", "serena-slim"]
+    }
+  }
+}
+```
+
+</details>
+
+## How It Works
+
+MCPSlim acts as a **transparent bridge** between AI models and the original MCP server:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Without MCPSlim                                                │
+│                                                                 │
+│  [AI Model] ──── reads 29 tool schemas ────→ [Original MCP]    │
+│             (~23,878 tokens loaded into context)                 │
+├─────────────────────────────────────────────────────────────────┤
+│  With MCPSlim                                                   │
+│                                                                 │
+│  [AI Model] ───→ [MCPSlim Bridge] ───→ [Original MCP]           │
+│       │                │                      │                 │
+│   Sees 18 grouped      Translates to        Executes actual   │
+│   tools only         original call       tool & returns    │
+│   (~11,655 tokens)                                              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### How Translation Works
+
+1. **AI reads slim schema** — Only 18 grouped tools instead of 29
+2. **AI calls grouped tool** — e.g., `interaction({ action: "click", ... })`
+3. **MCPSlim translates** — Converts to original: `browser_click({ ... })`
+4. **Original MCP executes** — Real server processes the request
+5. **Response returned** — Result passes back unchanged
+
+**Zero functionality loss. 51.2% token savings.**
+
+## Available Tool Groups
+
+| Group | Actions |
+|-------|---------|
+| `read` | 2 |
+| `list` | 2 |
+| `find` | 3 |
+| `replace` | 2 |
+| `get` | 2 |
+| `insert` | 2 |
+| `think` | 3 |
+| `memory` | 3 |
+
+Plus **10 passthrough tools** — tools that don't group well are kept as-is with optimized descriptions.
+
+## Compatibility
+
+- ✅ **Full functionality** — All original `serena` features preserved
+- ✅ **All AI assistants** — Works with Claude, ChatGPT, Gemini, Copilot, and any MCP client
+- ✅ **Drop-in replacement** — Same capabilities, just use grouped action names
+- ✅ **Tested** — Schema compatibility verified via automated tests
+
+## FAQ
+
+### Does this reduce functionality?
+
+**No.** Every original tool is accessible. Tools are grouped semantically (e.g., `click`, `hover`, `drag` → `interaction`), but all actions remain available via the `action` parameter.
+
+### Why do AI assistants need token optimization?
+
+AI models have limited context windows. MCP tool schemas consume tokens that could be used for conversation, code, or documents. Reducing tool schema size means more room for actual work.
+
+### Is this officially supported?
+
+MCPSlim is a community project. It wraps official MCP servers transparently — the original server does all the real work.
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  Powered by <a href="https://github.com/mcpslim/mcpslim"><b>MCPSlim</b></a> — MCP Token Optimizer
+  <br>
+  <sub>Reduce AI context usage. Keep full functionality.</sub>
+</p>

package/index.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+/**
+ * serena-slim - Slimmed serena MCP for Claude
+ * Reduces token usage by grouping similar tools
+ *
+ * Usage:
+ *   npx serena-slim                    # Run MCP server
+ *   npx serena-slim --setup            # Auto-configure (interactive)
+ *   npx serena-slim --setup claude     # Auto-configure for Claude Desktop
+ *   npx serena-slim --setup cursor     # Auto-configure for Cursor
+ */
+
+const { spawn, execSync } = require('child_process');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+const readline = require('readline');
+
+const MCP_NAME = 'serena';
+const PACKAGE_NAME = 'serena-slim';
+
+// 환경변수 요구사항 (빌드 시 주입)
+const REQUIRED_ENV_VARS = [];
+
+// ============================================
+// Setup Mode: Auto-configure MCP clients
+// ============================================
+
+const CONFIG_PATHS = {
+  'claude': getClaudeDesktopConfigPath(),
+  'claude-desktop': getClaudeDesktopConfigPath(),
+  'cursor': getCursorConfigPath(),
+};
+
+function getClaudeDesktopConfigPath() {
+  if (os.platform() === 'win32') {
+    return path.join(process.env.APPDATA || '', 'Claude', 'claude_desktop_config.json');
+  } else if (os.platform() === 'darwin') {
+    return path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  } else {
+    return path.join(os.homedir(), '.config', 'claude', 'claude_desktop_config.json');
+  }
+}
+
+function getCursorConfigPath() {
+  // Global config
+  if (os.platform() === 'win32') {
+    return path.join(process.env.APPDATA || '', 'Cursor', 'User', 'globalStorage', 'mcp.json');
+  } else {
+    return path.join(os.homedir(), '.cursor', 'mcp.json');
+  }
+}
+
+function addToConfig(configPath, mcpName, mcpConfig) {
+  let config = { mcpServers: {} };
+
+  // 디렉토리 생성
+  const dir = path.dirname(configPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  // 기존 설정 로드
+  if (fs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+      if (!config.mcpServers) config.mcpServers = {};
+    } catch (e) {
+      console.error('⚠️  Failed to parse existing config, creating new one');
+    }
+  }
+
+  // 이미 존재하는지 확인
+  if (config.mcpServers[mcpName]) {
+    console.log(`ℹ️  ${mcpName} already configured in ${configPath}`);
+    return false;
+  }
+
+  // 새 MCP 추가
+  config.mcpServers[mcpName] = mcpConfig;
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+  console.log(`✅ Added ${mcpName} to ${configPath}`);
+  return true;
+}
+
+async function interactiveSetup() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  const question = (q) => new Promise(resolve => rl.question(q, resolve));
+
+  console.log('\n🔧 ' + PACKAGE_NAME + ' Setup\n');
+  console.log('Select your MCP client:\n');
+  console.log('  1. Claude Desktop');
+  console.log('  2. Cursor');
+  console.log('  3. Claude Code (CLI)');
+  console.log('  4. VS Code (Copilot)');
+  console.log('  5. Cancel\n');
+
+  const choice = await question('Enter choice (1-5): ');
+  rl.close();
+
+  // 환경변수 플래그 생성
+  const envFlags = REQUIRED_ENV_VARS.map(v => `--env ${v}=<YOUR_${v.split('_').pop()}>`).join(' ');
+  const envJson = REQUIRED_ENV_VARS.length > 0
+    ? `,"env":{${REQUIRED_ENV_VARS.map(v => `"${v}":"<YOUR_${v.split('_').pop()}>"`).join(',')}}`
+    : '';
+
+  switch (choice.trim()) {
+    case '1':
+      return setupClient('claude');
+    case '2':
+      return setupClient('cursor');
+    case '3':
+      console.log('\nRun this command:\n');
+      if (REQUIRED_ENV_VARS.length > 0) {
+        console.log(`  claude mcp add ${MCP_NAME} ${envFlags} -- npx -y ${PACKAGE_NAME}\n`);
+      } else {
+        console.log(`  claude mcp add ${MCP_NAME} -- npx -y ${PACKAGE_NAME}\n`);
+      }
+      return true;
+    case '4':
+      console.log('\nRun this command:\n');
+      console.log(`  code --add-mcp '{"name":"${MCP_NAME}","command":"npx","args":["-y","${PACKAGE_NAME}"]${envJson}}'\n`);
+      return true;
+    case '5':
+    default:
+      console.log('Cancelled.');
+      return false;
+  }
+}
+
+function setupClient(client) {
+  const configPath = CONFIG_PATHS[client];
+  if (!configPath) {
+    console.error(`❌ Unknown client: ${client}`);
+    console.log('Supported: claude, claude-desktop, cursor');
+    return false;
+  }
+
+  const mcpConfig = {
+    command: 'npx',
+    args: ['-y', PACKAGE_NAME]
+  };
+
+  // 환경변수가 필요한 경우 env 블록 추가 (플레이스홀더)
+  if (REQUIRED_ENV_VARS.length > 0) {
+    mcpConfig.env = {};
+    for (const envVar of REQUIRED_ENV_VARS) {
+      mcpConfig.env[envVar] = `<YOUR_${envVar.split('_').pop()}>`;
+    }
+  }
+
+  const success = addToConfig(configPath, MCP_NAME, mcpConfig);
+
+  if (success) {
+    if (REQUIRED_ENV_VARS.length > 0) {
+      console.log(`\n⚠️  This MCP requires environment variables!`);
+      console.log(`   Edit ${configPath} and update:`);
+      for (const envVar of REQUIRED_ENV_VARS) {
+        console.log(`     - ${envVar}`);
+      }
+      console.log(`\n🎉 Setup complete! Update env vars, then restart ${client}.\n`);
+    } else {
+      console.log(`\n🎉 Setup complete! Restart ${client} to use ${MCP_NAME}.\n`);
+    }
+  }
+
+  return success;
+}
+
+// ============================================
+// Main: Check for --setup flag
+// ============================================
+
+const args = process.argv.slice(2);
+const setupIndex = args.indexOf('--setup');
+
+if (setupIndex !== -1) {
+  const client = args[setupIndex + 1];
+
+  if (client && !client.startsWith('-')) {
+    // Specific client: npx xxx-slim --setup claude
+    setupClient(client);
+  } else {
+    // Interactive: npx xxx-slim --setup
+    interactiveSetup().then(() => process.exit(0));
+  }
+} else {
+  // ============================================
+  // Normal Mode: Run MCP server
+  // ============================================
+
+  const binName = os.platform() === 'win32' ? 'mcpslim.exe' : 'mcpslim';
+  const mcpslimBin = path.join(__dirname, 'bin', binName);
+  const recipePath = path.join(__dirname, 'recipes', 'serena.json');
+
+  // 원본 MCP 명령어
+  const originalMcp = process.env.MCPSLIM_ORIGINAL_MCP?.split(' ')
+    || ["uvx","--from","git+https://github.com/oraios/serena","serena","start-mcp-server"];
+
+  const bridgeArgs = ['bridge', '--recipe', recipePath, '--', ...originalMcp];
+
+  const child = spawn(mcpslimBin, bridgeArgs, {
+    stdio: 'inherit',
+    windowsHide: true
+  });
+
+  child.on('error', (err) => {
+    console.error('Failed to start MCPSlim:', err.message);
+    process.exit(1);
+  });
+
+  child.on('exit', (code) => process.exit(code || 0));
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "serena-slim",
+  "version": "0.0.1-slim.1",
+  "description": "Slimmed serena MCP - 38% token reduction for AI models",
+  "bin": {
+    "serena-slim": "./index.js"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "gemini",
+    "chatgpt",
+    "serena",
+    "slim",
+    "token-reduction"
+  ],
+  "author": "",
+  "license": "MIT",
+  "files": [
+    "bin/",
+    "recipes/",
+    "index.js",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/palan-k/mcpslim.git",
+    "directory": "packages/serena-slim"
+  },
+  "mcpslim": {
+    "originalPackage": "serena",
+    "originalVersion": "0.0.1",
+    "originalTools": 29,
+    "slimTools": 18,
+    "tokenReduction": "38%"
+  }
+}

package/recipes/serena.json

@@ -0,0 +1,380 @@
+{
+  "mcp_name": "serena",
+  "auto_generated": true,
+  "algorithm_version": "v2.1",
+  "rules": {
+    "default_minifier": "first_sentence",
+    "remove_params_description": true
+  },
+  "groups": [
+    {
+      "name": "read",
+      "description": "Access file contents or relevant memory data to provide contextual information for the current task.",
+      "mapping": {
+        "file": "read_file",
+        "memory": "read_memory"
+      },
+      "common_schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": [
+              "file",
+              "memory"
+            ]
+          },
+          "relative_path": {
+            "type": "string"
+          },
+          "start_line": {
+            "type": "integer",
+            "default": 0
+          },
+          "end_line": {
+            "default": null
+          },
+          "max_answer_chars": {
+            "type": "integer",
+            "default": -1
+          },
+          "memory_file_name": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "action",
+          "relative_path",
+          "memory_file_name"
+        ]
+      }
+    },
+    {
+      "name": "list",
+      "description": "Explore filesystem contents and available memories to locate specific files or data storage.",
+      "mapping": {
+        "dir": "list_dir",
+        "memories": "list_memories"
+      },
+      "common_schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": [
+              "dir",
+              "memories"
+            ]
+          },
+          "relative_path": {
+            "type": "string"
+          },
+          "recursive": {
+            "type": "boolean"
+          },
+          "skip_ignored_files": {
+            "type": "boolean",
+            "default": false
+          },
+          "max_answer_chars": {
+            "type": "integer",
+            "default": -1
+          }
+        },
+        "required": [
+          "action",
+          "relative_path",
+          "recursive"
+        ]
+      }
+    },
+    {
+      "name": "find",
+      "description": "Locate files, discover code symbols, and pinpoint references to specific symbols within a codebase.",
+      "mapping": {
+        "file": "find_file",
+        "symbol": "find_symbol",
+        "referencing_symbols": "find_referencing_symbols"
+      },
+      "common_schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": [
+              "file",
+              "symbol",
+              "referencing_symbols"
+            ]
+          },
+          "file_mask": {
+            "type": "string"
+          },
+          "relative_path": {
+            "type": "string"
+          },
+          "name_path_pattern": {
+            "type": "string"
+          },
+          "depth": {
+            "type": "integer",
+            "default": 0
+          },
+          "include_body": {
+            "type": "boolean",
+            "default": false
+          },
+          "include_kinds": {
+            "type": "array",
+            "default": [],
+            "items": {
+              "type": "integer"
+            }
+          },
+          "exclude_kinds": {
+            "type": "array",
+            "default": [],
+            "items": {
+              "type": "integer"
+            }
+          },
+          "substring_matching": {
+            "type": "boolean",
+            "default": false
+          },
+          "max_answer_chars": {
+            "type": "integer",
+            "default": -1
+          },
+          "name_path": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "action",
+          "file_mask",
+          "relative_path",
+          "name_path_pattern",
+          "name_path"
+        ]
+      }
+    },
+    {
+      "name": "replace",
+      "description": "Replace file content via pattern matching or directly substitute the body of identified code symbols.",
+      "mapping": {
+        "content": "replace_content",
+        "symbol_body": "replace_symbol_body"
+      },
+      "common_schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": [
+              "content",
+              "symbol_body"
+            ]
+          },
+          "relative_path": {
+            "type": "string"
+          },
+          "needle": {
+            "type": "string"
+          },
+          "repl": {
+            "type": "string"
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "literal",
+              "regex"
+            ]
+          },
+          "allow_multiple_occurrences": {
+            "type": "boolean",
+            "default": false
+          },
+          "name_path": {
+            "type": "string"
+          },
+          "body": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "action",
+          "relative_path",
+          "needle",
+          "repl",
+          "mode",
+          "name_path",
+          "body"
+        ]
+      }
+    },
+    {
+      "name": "get",
+      "description": "Analyze code symbols within files and display the agent’s current working configuration details.",
+      "mapping": {
+        "symbols_overview": "get_symbols_overview",
+        "current_config": "get_current_config"
+      },
+      "common_schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": [
+              "symbols_overview",
+              "current_config"
+            ]
+          },
+          "relative_path": {
+            "type": "string"
+          },
+          "depth": {
+            "type": "integer",
+            "default": 0
+          },
+          "max_answer_chars": {
+            "type": "integer",
+            "default": -1
+          }
+        },
+        "required": [
+          "action",
+          "relative_path"
+        ]
+      }
+    },
+    {
+      "name": "insert",
+      "description": "Modify code by precisely inserting new content either before or after existing symbol definitions.",
+      "mapping": {
+        "after_symbol": "insert_after_symbol",
+        "before_symbol": "insert_before_symbol"
+      },
+      "common_schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": [
+              "after_symbol",
+              "before_symbol"
+            ]
+          },
+          "name_path": {
+            "type": "string"
+          },
+          "relative_path": {
+            "type": "string"
+          },
+          "body": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "action",
+          "name_path",
+          "relative_path",
+          "body"
+        ]
+      }
+    },
+    {
+      "name": "think",
+      "description": "Evaluate gathered information, task progress, and completion status to guide effective AI assistant reasoning.",
+      "mapping": {
+        "about_collected_information": "think_about_collected_information",
+        "about_task_adherence": "think_about_task_adherence",
+        "about_whether_you_are_done": "think_about_whether_you_are_done"
+      },
+      "common_schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": [
+              "about_collected_information",
+              "about_task_adherence",
+              "about_whether_you_are_done"
+            ]
+          }
+        },
+        "required": [
+          "action"
+        ]
+      }
+    },
+    {
+      "name": "memory",
+      "description": "Manage persistent project knowledge by storing, deleting, and regex-based updating of markdown files.",
+      "mapping": {
+        "write": "write_memory",
+        "delete": "delete_memory",
+        "edit": "edit_memory"
+      },
+      "common_schema": {
+        "type": "object",
+        "properties": {
+          "action": {
+            "type": "string",
+            "enum": [
+              "write",
+              "delete",
+              "edit"
+            ]
+          },
+          "memory_file_name": {
+            "type": "string"
+          },
+          "content": {
+            "type": "string"
+          },
+          "max_answer_chars": {
+            "type": "integer",
+            "default": -1
+          },
+          "needle": {
+            "type": "string"
+          },
+          "repl": {
+            "type": "string"
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "literal",
+              "regex"
+            ]
+          }
+        },
+        "required": [
+          "action",
+          "memory_file_name",
+          "content",
+          "needle",
+          "repl",
+          "mode"
+        ]
+      }
+    }
+  ],
+  "passthrough": [
+    "create_text_file",
+    "search_for_pattern",
+    "rename_symbol",
+    "execute_shell_command",
+    "activate_project",
+    "switch_modes",
+    "check_onboarding_performed",
+    "onboarding",
+    "prepare_for_new_conversation",
+    "initial_instructions"
+  ],
+  "ai_enhanced": true,
+  "enhanced_at": "2026-01-05T07:32:33.116Z"
+}