PrincipalMD - Industrial Markdown for VS Code

Display and interact with Industrial Markdown directly in VS Code, with MCP (Model Context Protocol) integration for AI agents like Claude and Cursor.

Features

🚀 Industrial Markdown Viewer

• Advanced markdown rendering with interactive elements
• Checkbox support with real-time updates
• Code block execution
• Mermaid diagram support
• Dark/Light theme support

🤖 MCP Integration

Enable AI agents to display rich markdown content directly in your VS Code window:

• MCP Bridge: Allows communication between AI agents and VS Code
• Direct Display: AI agents can show markdown content in dedicated panels
• File Access: Open and display markdown files through MCP tools

📁 Markdown Explorer

• Browse and navigate markdown files in your workspace
• Quick file preview
• Favorites system for frequently accessed documents

Quick Start

1. Start the MCP Bridge

1. Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Run PrincipalMD: Start MCP Bridge
3. The bridge will start on port 3045 (configurable)

2. Configure Your AI Agent

For Claude Desktop

Add to your Claude configuration file:

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

{
  "mcpServers": {
    "principalMD": {
      "command": "principalmd-mcp"
    }
  }
}

For Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "principalMD": {
      "command": "principalmd-mcp"
    }
  }
}

Note: You'll need to install the MCP server separately:

npm install -g @principalmd/mcp-server

3. Use MCP Tools in Your AI Agent

Once configured, your AI agent can use these tools:

• showMarkdownContent: Display markdown content in VS Code
• openMarkdownFile: Open a markdown file in the Industrial Markdown viewer
• getMarkdown: Retrieve the current markdown content from VS Code (for editing workflows)
• getAppInfo: Get information about the extension status

Example prompt for Claude:

Use the showMarkdownContent tool to display a summary of this conversation in markdown format

Requirements

• VS Code 1.60.0 or higher
• Node.js (for MCP server functionality)

Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
3. Search for "PrincipalMD"
4. Click Install

From VSIX Package

1. Download the .vsix file
2. Open Command Palette
3. Run Extensions: Install from VSIX...
4. Select the downloaded file

Commands

• PrincipalMD: Start MCP Bridge - Start the HTTP bridge for MCP communication
• PrincipalMD: Stop MCP Bridge - Stop the MCP bridge
• PrincipalMD: Open Industrial Markdown - Open the Industrial Markdown viewer
• PrincipalMD: Show Welcome - Show the welcome screen with setup instructions

Configuration

Extension Settings

• principalMD.mcpBridgePort: Port for the MCP HTTP bridge (default: 3045)
• principalMD.showWelcomeOnStartup: Show welcome screen on startup (default: true)

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  AI Agent   │────▶│ MCP Server  │────▶│ HTTP Bridge │────▶│   VS Code   │
│  (Claude)   │     │(mcp-server) │     │ (Port 3043) │     │  Extension  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                         stdio                HTTP              WebView

Troubleshooting

MCP Bridge won't start

• Ensure port 3043 is not in use
• Check VS Code Developer Console for errors
• Try restarting VS Code

AI Agent can't connect

• Verify the MCP Bridge is running (check status bar)
• Ensure the MCP server path is correct in your AI agent config
• Check that Node.js is installed and accessible

Content not displaying

• Ensure the Industrial Markdown panel is open
• Check that the MCP Bridge is running
• Verify the AI agent is using the correct tool names

Support

• GitHub Issues: Report bugs or request features
• Documentation: Full documentation

License

MIT

Contributors

• PrincipalMD Team
• Community Contributors

Made with ❤️ by PrincipalMD