cyj0920/jlink_mcp

---

English Documentation

🚀 Overview

JLink MCP Server is a comprehensive debugging tool that integrates J-Link debugger capabilities with AI assistants through the Model Context Protocol. It provides seamless access to hardware debugging features including memory operations, flash programming, register access, and real-time data transfer.

✨ Key Features

📋 Prerequisites

• Python: 3.8 or higher
• J-Link Software: Latest version from Segger
• J-Link Hardware: Any supported J-Link debugger
• Operating System: Windows, Linux, or macOS

🛠️ Installation

Method 1: Install from PyPI

pip install jlink-mcp

Method 2: Install from Source

# Clone the repository
git clone https://github.com/cyj0920/jlink_mcp.git
cd jlink_mcp

# Install in development mode
pip install -e .

Method 3: Install with UV (Recommended for better performance)

# Install UV
pip install uv

# Install with UV
uv pip install jlink-mcp

⚙️ Configuration

Environment Variables

Create a .env file or set environment variables:

# Optional: External SVD directory for peripheral register definitions
JLINK_SVD_DIR=/path/to/svd/files

# Optional: External device patch directory for vendor-specific support
JLINK_PATCH_DIR=/path/to/patches

# Optional: Default interface type (SWD or JTAG)
JLINK_DEFAULT_INTERFACE=JTAG

MCP Configuration

Add to your MCP configuration file (typically ~/.config/mcp/settings.json or C:\Users\\.iflow\settings.json):

{
  "mcpServers": {
    "jlink": {
      "command": "python",
      "args": ["-m", "jlink_mcp"],
      "env": {
        "JLINK_SVD_DIR": "C:\\path\\to\\svd\\files",
        "JLINK_PATCH_DIR": "C:\\path\\to\\patches",
        "JLINK_DEFAULT_INTERFACE": "JTAG"
      }
    }
  }
}

📖 Usage Guide

Connecting to Devices

Memory Operations

Flash Programming

Debug Control

Register Access

SVD Register Access

Breakpoints and Debugging

RTT (Real-Time Transfer)

🏗️ Architecture

The server follows a modular, plugin-based architecture:

┌─────────────────────────────────────────────────┐
│           JLink MCP Server                       │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌──────────────┐  ┌────────────────────┐     │
│  │   Server     │  │   Tool Layer       │     │
│  │   Manager    │  │                    │     │
│  └──────┬───────┘  │  • Connection      │     │
│         │          │  • Debug           │     │
│         │          │  • Memory          │     │
│         │          │  • Flash           │     │
│         │          │  • Registers       │     │
│         │          │  • SVD             │     │
│         │          │  • RTT             │     │
│         │          └────────────────────┘     │
│         │                                        │
│  ┌──────▼────────────────────────────────┐      │
│  │         Manager Layer                  │      │
│  ├────────────┬────────────┬─────────────┤      │
│  │ JLink      │ SVD        │ Patch       │      │
│  │ Manager    │ Manager    │ Manager     │      │
│  └────────────┴────────────┴─────────────┘      │
│                                                 │
│  ┌──────────────────────────────────────────┐   │
│  │         Plugin Layer                      │   │
│  │  • DevicePatchInterface                  │   │
│  │  • Vendor-specific patches               │   │
│  └──────────────────────────────────────────┘   │
│                                                 │
│  ┌──────────────────────────────────────────┐   │
│  │         Hardware Layer                    │   │
│  │  • pylink-square                          │   │
│  │  • J-Link SDK                            │   │
│  └──────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘

🧩 Plugin System

The server supports a flexible plugin architecture for device-specific functionality:

Creating a Custom Patch

from typing import Optional, List, Dict, Any
from jlink_mcp.device_patch_interface import DevicePatchInterface

class CustomDevicePatch(DevicePatchInterface):
    """Custom device patch implementation."""

    @property
    def vendor_name(self) -> str:
        """Return the vendor name."""
        return "CustomVendor"

    @property
    def patch_version(self) -> str:
        """Return the patch version."""
        return "v1.0.0"

    def is_available(self) -> bool:
        """Check if the patch is available."""
        return True

    def match_device_name(self, chip_name: str) -> Optional[str]:
        """
        Match and return the full device name.

        Args:
            chip_name: Partial or simplified device name

        Returns:
            Full device name or None if no match
        """
        # Implement your matching logic
        device_map = {
            "CUSTOM": "CustomDevice1",
            "CUST1": "CustomDevice1",
        }
        return device_map.get(chip_name.upper())

    @property
    def device_names(self) -> List[str]:
        """Return list of supported devices."""
        return ["CustomDevice1", "CustomDevice2"]

    def get_device_info(self, device_name: str) -> Optional[Dict[str, Any]]:
        """
        Get detailed information about a device.

        Args:
            device_name: Full device name

        Returns:
            Device information dictionary
        """
        return {
            "name": device_name,
            "vendor": self.vendor_name,
            "core": "ARM Cortex-M4",
            "flash_size": 512 * 1024,
            "ram_size": 128 * 1024,
        }

Registering a Custom Patch

from jlink_mcp.device_patch_manager import device_patch_manager

# Create and register your custom patch
custom_patch = CustomDevicePatch()
device_patch_manager.register_patch(custom_patch)

📚 API Reference

The server provides 41 MCP tools across 9 categories:

Connection API (5 tools)

Device Info API (4 tools)

Memory API (4 tools)

Flash API (3 tools)

Debug API (7 tools)

RTT API (5 tools)

GDB Server API (3 tools)

SVD API (5 tools)

Guidance API (5 tools)

🐛 Troubleshooting

Common Issues

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Segger for J-Link hardware and software
• pylink-square for the Python J-Link library
• Model Context Protocol for the MCP specification

---

中文文档

🚀 概述

JLink MCP Server 是一个功能强大的调试工具，通过模型上下文协议将J-Link调试器功能与AI助手集成。它提供无缝的硬件调试功能访问，包括内存操作、Flash编程、寄存器访问和实时数据传输。

✨ 核心特性

📋 前置要求

• Python: 3.8 或更高版本
• J-Link软件: 从 Segger 获取最新版本
• J-Link硬件: 任何支持的J-Link调试器
• 操作系统: Windows、Linux 或 macOS

🛠️ 安装

方法1：从PyPI安装

pip install jlink-mcp

方法2：从源码安装

# 克隆仓库
git clone https://github.com/cyj0920/jlink_mcp.git
cd jlink_mcp

# 开发模式安装
pip install -e .

方法3：使用UV安装（推荐，性能更好）

# 安装UV
pip install uv

# 使用UV安装
uv pip install jlink-mcp

⚙️ 配置

环境变量

创建 .env 文件或设置环境变量：

# 可选：外部SVD目录，用于外设寄存器定义
JLINK_SVD_DIR=/path/to/svd/files

# 可选：外部设备补丁目录，用于厂商特定支持
JLINK_PATCH_DIR=/path/to/patches

# 可选：默认接口类型（SWD或JTAG）
JLINK_DEFAULT_INTERFACE=JTAG

MCP配置

添加到你的MCP配置文件（通常在 ~/.config/mcp/settings.json 或 C:\Users\\.iflow\settings.json）：

{
  "mcpServers": {
    "jlink": {
      "command": "python",
      "args": ["-m", "jlink_mcp"],
      "env": {
        "JLINK_SVD_DIR": "C:\\path\\to\\svd\\files",
        "JLINK_PATCH_DIR": "C:\\path\\to\\patches",
        "JLINK_DEFAULT_INTERFACE": "JTAG"
      }
    }
  }
}

📖 使用指南

连接设备

内存操作

Flash编程

调试控制

寄存器访问

SVD寄存器访问

断点和调试

RTT（实时传输）

🏗️ 架构

服务器采用模块化、基于插件的架构：

┌─────────────────────────────────────────────────┐
│           JLink MCP Server                       │
├─────────────────────────────────────────────────┤
│                                                 │
│  ┌──────────────┐  ┌────────────────────┐     │
│  │   Server     │  │   工具层           │     │
│  │   Manager    │  │                    │     │
│  └──────┬───────┘  │  • 连接            │     │
│         │          │  • 调试            │     │
│         │          │  • 内存            │     │
│         │          │  • Flash           │     │
│         │          │  • 寄存器          │     │
│         │          │  • SVD             │     │
│         │          │  • RTT             │     │
│         │          └────────────────────┘     │
│         │                                        │
│  ┌──────▼────────────────────────────────┐      │
│  │         管理器层                        │      │
│  ├────────────┬────────────┬─────────────┤      │
│  │ JLink      │ SVD        │ 补丁        │      │
│  │ 管理器     │ 管理器     │ 管理器      │      │
│  └────────────┴────────────┴─────────────┘      │
│                                                 │
│  ┌──────────────────────────────────────────┐   │
│  │         插件层                           │   │
│  │  • DevicePatchInterface                  │   │
│  │  • 厂商特定补丁                          │   │
│  └──────────────────────────────────────────┘   │
│                                                 │
│  ┌──────────────────────────────────────────┐   │
│  │         硬件层                           │   │
│  │  • pylink-square                          │   │
│  │  • J-Link SDK                            │   │
│  └──────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘

🧩 插件系统

服务器支持灵活的插件架构，用于设备特定功能：

创建自定义补丁

from typing import Optional, List, Dict, Any
from jlink_mcp.device_patch_interface import DevicePatchInterface

class CustomDevicePatch(DevicePatchInterface):
    """自定义设备补丁实现。"""

    @property
    def vendor_name(self) -> str:
        """返回厂商名称。"""
        return "CustomVendor"

    @property
    def patch_version(self) -> str:
        """返回补丁版本。"""
        return "v1.0.0"

    def is_available(self) -> bool:
        """检查补丁是否可用。"""
        return True

    def match_device_name(self, chip_name: str) -> Optional[str]:
        """
        匹配并返回完整的设备名称。

        Args:
            chip_name: 部分或简化的设备名称

        Returns:
            完整的设备名称或None（如果不匹配）
        """
        # 实现你的匹配逻辑
        device_map = {
            "CUSTOM": "CustomDevice1",
            "CUST1": "CustomDevice1",
        }
        return device_map.get(chip_name.upper())

    @property
    def device_names(self) -> List[str]:
        """返回支持的设备列表。"""
        return ["CustomDevice1", "CustomDevice2"]

    def get_device_info(self, device_name: str) -> Optional[Dict[str, Any]]:
        """
        获取设备的详细信息。

        Args:
            device_name: 完整的设备名称

        Returns:
            设备信息字典
        """
        return {
            "name": device_name,
            "vendor": self.vendor_name,
            "core": "ARM Cortex-M4",
            "flash_size": 512 * 1024,
            "ram_size": 128 * 1024,
        }

注册自定义补丁

from jlink_mcp.device_patch_manager import device_patch_manager

# 创建并注册你的自定义补丁
custom_patch = CustomDevicePatch()
device_patch_manager.register_patch(custom_patch)

📚 API参考

核心函数

🐛 故障排除

常见问题

🤝 贡献

欢迎贡献！请遵循以下准则：

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📝 许可证

本项目采用MIT许可证 - 详见 LICENSE 文件。

🙏 致谢

• Segger 提供J-Link硬件和软件
• pylink-square 提供Python J-Link库
• Model Context Protocol 提供MCP规范

---