MCP Nrepl Joyride

MCP nREPL Joyride桥

基于Babashka的MCP（模型上下文协议）服务器，将Claude Code与运行在VS Code中的Joyride的nREPL服务器连接起来。

🎯 概述

该项目通过提供nREPL，使Claude Code能够通过Joyride直接控制VS Code→ MCP翻译层。Claude Code可以通过Joyride评估操纵VS Code的API的Clojure表达式。

Claude Code ↔ [MCP-nREPL Proxy] ↔ [Joyride nREPL] ↔ [VS Code APIs]

⚡ 特性

• 纯Babashka实现 -快速启动（~200ms）和低内存使用率（~50MB）
• 自定义nREPL客户端 -基于Babashka兼容套接字的nREPL通信
• 🆕 显式连接架构 -具有所需端口参数的强大连接管理（无脆弱的自动发现）
• 🆕 100%测试可靠性 -全面的测试套件，11/11测试始终如一地通过
• 🆕 动态端口分配 -防止与bb-nrepl服务器发生冲突，并消除断线错误
• 符合MCP标准 -通过工具和资源提供完整的模型上下文协议支持
• 会话管理 -跟踪和管理孤立的nREPL评估会话
• Joyrid/Calva集成 -完全支持VS Code API调用和Calva中间件
• 增强测试 -具有完整生命周期测试的多种测试模式（完整/快速/仅服务器）
• 工作区操作 -文件列表、文档操作和通知支持
• 🆕 通用stdio MCP测试客户端 -适用于任何stdio MCP服务器的生产现实测试工具

🚀 快速开始

先决条件

1. 巴巴什卡 安装
2. 紫外线的 已安装（用于Python工具）
3. VS代码 Joyride扩展
4. Joyride nREPL服务器在您的VS Code工作区中运行

安装

# Clone the repository
git clone https://github.com/franks42/mcp-nrepl-joyride.git
cd mcp-nrepl-joyride

# Install Python dependencies
uv sync

# Start server using management script (recommended)
uv run python mcp_server_manager.py start

# OR test the server directly
bb mcp-server

服务器管理

该项目包括 mcp_server_manager.py 为了简化服务器操作：

# Start server in background
uv run python mcp_server_manager.py start

# Check server status
uv run python mcp_server_manager.py status

# Run comprehensive health check
uv run python mcp_server_manager.py health

# Run basic functionality tests
uv run python mcp_server_manager.py test

# Show available MCP tools
uv run python mcp_server_manager.py tools

# Full workflow (start + test + health check)
uv run python mcp_server_manager.py run

# Stop server
uv run python mcp_server_manager.py stop

# Restart server
uv run python mcp_server_manager.py restart

Claude代码配置

添加到您的Claude Code MCP配置中：

{
  "mcpServers": {
    "joyride-nrepl": {
      "command": "bb",
      "args": ["-f", "/path/to/mcp-nrepl-joyride/bb.edn", "mcp-server"],
      "env": {
        "JOYRIDE_WORKSPACE": "${workspaceFolder}",
        "MCP_DEBUG": "false"
      }
    }
  }
}

🛠️ 可用的MCP工具

nrepl-connect

使用显式端口参数连接到nREPL服务器（强健连接管理所需）。

参数：

• port （必填）：nREPL服务器端口号
• host （可选）：服务器主机（默认为“localhost”）

例子：

{"port": 56789}

nrepl-eval

在nREPL会话中使用完整的Joyrid/Calva支持评估Clojure代码。

示例：

;; Simple evaluation
(+ 1 2 3)

;; VS Code interaction via Joyride
(joyride.core/execute-command "workbench.action.quickOpen")

;; Access VS Code APIs
(-> js/vscode.window.activeTextEditor .-document .-fileName)

;; Workspace operations
(joyride/workspace-root)
(joyride/workspace-files "**/*.clj")

;; VS Code notifications
(vscode.window.showInformationMessage "Hello from Claude!")

nrepl-status

获取连接状态和会话信息。

nrepl-new-session

为独立评估创建新的nREPL会话。

🎨 使用Claude代码的示例用法

配置后，Claude Code可以直接操作VS Code：

“打开src/core.clj文件并突出显示第42行”

(do
  (require '[joyride.core :as joyride])
  (joyride/execute-command "vscode.open" 
    (str (joyride/workspace-root) "/src/core.clj"))
  (joyride/execute-command "revealLine" {:lineNumber 42 :at "center"}))

“显示工作区中的所有Clojure文件”

(->> (joyride/workspace-files "**/*.clj")
     (map #(.-path %))
     (sort))

🔧 发展

🧪 stdio MCP测试（推荐） - 🆕

测试用户体验的REAL stdio界面：

# Test basic MCP protocol
uv run python stdio_mcp_client.py \
  --server-cmd "bb -cp src src/mcp_nrepl_proxy/core.clj" \
  --test-basic

# Test nREPL functionality
uv run python stdio_mcp_client.py \
  --server-cmd "bb -cp src src/mcp_nrepl_proxy/core.clj" \
  --test-nrepl

# List available tools
uv run python stdio_mcp_client.py \
  --server-cmd "bb -cp src src/mcp_nrepl_proxy/core.clj" \
  --list-tools --pretty

# Call specific tools
uv run python stdio_mcp_client.py \
  --server-cmd "bb -cp src src/mcp_nrepl_proxy/core.clj" \
  --tool nrepl-eval --args '{"code": "(+ 1 2 3)"}'

HTTP服务器管理（替代方案）

# Full development workflow
uv run python mcp_server_manager.py run

# Start server for development
uv run python mcp_server_manager.py start --port 3005 --foreground

# Monitor server status during development
uv run python mcp_server_manager.py status

直接巴巴什卡命令

# Start in debug mode
bb dev

# Run basic integration tests
bb -cp src run-integration-test.clj

# Run enhanced Joyride integration tests
bb -cp src test-joyride-integration.clj

# Start test nREPL server
bb test-nrepl-server

# Start enhanced Joyride mock server
bb joyride-mock-server

# Start development REPL
bb repl

# Build standalone jar
bb build

Python代码质量

所有Python代码更改都必须通过质量检查：

# Format Python code
uv run black mcp_server_manager.py

# Check code style
uv run flake8 mcp_server_manager.py

# Install development dependencies
uv add black flake8

🧪 测试

综合测试套件（新增！）

该项目现在包括一个全面的基于Python的测试套件，具有100%的可靠性：

# Full test suite (11 tests) - RECOMMENDED
python3 test_nrepl_lifecycle.py

# Quick test mode (7 tests) - Skip long-running tests
python3 test_nrepl_lifecycle.py --quick

# Server-only mode (5 tests) - Test lifecycle only
python3 test_nrepl_lifecycle.py --server-only

测试覆盖范围：

• ✅ 服务器生命周期管理（启动/停止/重新启动/状态）
• ✅ 具有显式连接的MCP代理集成
• ✅ 完整的Clojure功能（承诺、未来、Java互操作）
• ✅ 港口冲突解决和动态分配
• ✅ 错误处理和连接管理

测试服务器管理

# Managed Full Clojure nREPL Test Server
python3 nrepl_test_server.py start     # Auto-assigns port, tracks PID
python3 nrepl_test_server.py status    # Show connection info
python3 nrepl_test_server.py restart   # Clean restart
python3 nrepl_test_server.py stop      # Graceful shutdown

🏗️ 建筑

• 核心MCP服务器 在……里面 src/mcp_nrepl_proxy/core.clj -符合JSON-RPC 2.0标准
• 自定义nREPL客户端 在……里面 src/mcp_nrepl_proxy/nrepl_client.clj -基于套接字的Babashka兼容性
• 巴巴什卡本地人 -没有JVM启动惩罚，迭代速度快
• 🆕 显式连接架构 -强大的基于端口的连接（没有脆弱的自动发现）
• 🆕 动态端口分配 -防止与以下对象发生冲突 port_utils.py
• 🆕 全面的测试基础设施 -100%可靠性的全生命周期测试
• 会话隔离 -支持多个并发nREPL会话
• 错误处理 -优雅的降级和连接管理

📚 参考文献

• 模型上下文协议
• 巴巴什卡
• 兜风
• nREPL协议

🤝 贡献

该项目是通过VS Code集成实现人工智能辅助开发的更广泛努力的一部分。请参阅 docs/ 详细的实现说明和架构决策目录。

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。