{"_id":"@a24z/principal-md","_rev":"5-252960fbff9b3a870c824a1793dd0588","name":"@a24z/principal-md","dist-tags":{"latest":"0.2.1"},"versions":{"0.1.0":{"name":"@a24z/principal-md","version":"0.1.0","keywords":["mcp","model-context-protocol","markdown","visualization","principal"],"author":{"name":"a24z Team"},"license":"MIT","_id":"@a24z/principal-md@0.1.0","maintainers":[{"name":"principal-ai","email":"principle@principlemd.com"}],"homepage":"https://a24z.ai","bugs":{"url":"https://github.com/a24z-ai/principal.md/issues"},"bin":{"principal-md":"dist/cli.js"},"dist":{"shasum":"9b406d60834d593a50cf1cccff1b962596010aee","tarball":"https://registry.npmjs.org/@a24z/principal-md/-/principal-md-0.1.0.tgz","fileCount":27,"integrity":"sha512-i43ctJvlHHHBO0QEWDXG3NCpcj8wnTSXrj+VfLXCWtdITjLcSdufNgwjPCqFmiRJ2wJqIa0hl1NlxlifDNCgjw==","signatures":[{"sig":"MEUCIFgSJfi4JEPMFFu+HHVDddB9Zny2ZmD4oM2ioixMfTXZAiEAxxs/d9EHe8kzmu/kvubWsaW9jMvV4J2MBWS8pFRlFuY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44343},"main":"dist/lib.js","types":"dist/lib.d.ts","engines":{"node":">=18"},"gitHead":"e328543744c870b95ae4e9e4cec1dd38751fff12","private":false,"scripts":{"test":"jest","build":"tsc","prepare":"npm run build","release":"semantic-release","postbuild":"chmod +x dist/cli.js","test:watch":"jest --watch","test:coverage":"jest --coverage"},"_npmUser":{"name":"principal-ai","email":"principle@principlemd.com"},"repository":{"url":"git+https://github.com/a24z-ai/principal.md.git","type":"git"},"_npmVersion":"10.9.2","description":"Standalone Principal MD MCP server for markdown visualization","directories":{},"_nodeVersion":"23.11.0","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.0.4"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.5.0","ts-jest":"^29.1.0","typescript":"^5.6.3","@types/jest":"^29.5.0","@types/node":"^22.15.26","semantic-release":"^24.2.7","@semantic-release/git":"^10.0.1","@semantic-release/changelog":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/principal-md_0.1.0_1755736299951_0.8389534667311744","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@a24z/principal-md","version":"0.1.1","keywords":["mcp","model-context-protocol","markdown","visualization","principal"],"author":{"name":"a24z Team"},"license":"MIT","_id":"@a24z/principal-md@0.1.1","maintainers":[{"name":"principal-ai","email":"principle@principlemd.com"}],"homepage":"https://a24z.ai","bugs":{"url":"https://github.com/a24z-ai/principal.md/issues"},"bin":{"principal-md":"dist/cli.js"},"dist":{"shasum":"7f476937253c1633d0c7558f2bdb1e7774432e03","tarball":"https://registry.npmjs.org/@a24z/principal-md/-/principal-md-0.1.1.tgz","fileCount":27,"integrity":"sha512-aBzR49qWkxqZS37y2VUnJ56sn2j4gH9aVPi0PtEnzlqQ+zr1jEunaeJ69SIZn4BfTAnJC0TVN+jUw/4+vAYHJA==","signatures":[{"sig":"MEUCIHFOrMyfNHuAId+l3AsEZdlVlXpOePffP+5hebxOdsUxAiEAkHf/EvhnnY7gvJ8GvToUnRZaOU6CWhfk0AaQNsu9aJI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45323},"main":"dist/lib.js","types":"dist/lib.d.ts","engines":{"node":">=18"},"gitHead":"b63014dcee7eeb2af0079a992d59593d0d26ff03","private":false,"scripts":{"test":"jest","build":"tsc","prepare":"npm run build","release":"semantic-release","postbuild":"chmod +x dist/cli.js","test:watch":"jest --watch","test:coverage":"jest --coverage"},"_npmUser":{"name":"principal-ai","email":"principle@principlemd.com"},"repository":{"url":"git+https://github.com/a24z-ai/principal.md.git","type":"git"},"_npmVersion":"10.9.2","description":"Standalone Principal MD MCP server for markdown visualization","directories":{},"_nodeVersion":"23.11.0","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.0.4"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.5.0","ts-jest":"^29.1.0","typescript":"^5.6.3","@types/jest":"^29.5.0","@types/node":"^22.15.26","semantic-release":"^24.2.7","@semantic-release/git":"^10.0.1","@semantic-release/changelog":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/principal-md_0.1.1_1755736696582_0.5365881931046239","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@a24z/principal-md","version":"0.2.0","keywords":["mcp","model-context-protocol","markdown","visualization","principal"],"author":{"name":"a24z Team"},"license":"MIT","_id":"@a24z/principal-md@0.2.0","maintainers":[{"name":"principal-ai","email":"principle@principlemd.com"}],"homepage":"https://a24z.ai","bugs":{"url":"https://github.com/a24z-ai/principal.md/issues"},"bin":{"principal-md":"dist/cli.js"},"dist":{"shasum":"4b0873fa9d839e38ffc40d459981f50142a839a8","tarball":"https://registry.npmjs.org/@a24z/principal-md/-/principal-md-0.2.0.tgz","fileCount":27,"integrity":"sha512-7l/7tiKE8osgs9pSqThkj7yLmHSctjFUsJsdFdP6d+28UYy/QamFO26Lbszn+5jrK4WZZ41E/mSmTPdyb3Jklg==","signatures":[{"sig":"MEUCIGkiWZuo1qLlITUeslZqCbeAHWDb9Kdl/7kPbR7wuIYoAiEA7qP/Sz5Gvh7jAc1IvQzqC/jQjobCX4e1t/rxaaCNJb8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45436},"main":"dist/lib.js","types":"dist/lib.d.ts","engines":{"node":">=18"},"gitHead":"a94b438c63266a088c7705ce15422612094b248c","private":false,"scripts":{"test":"jest","build":"tsc","prepare":"npm run build","release":"semantic-release","postbuild":"chmod +x dist/cli.js","test:watch":"jest --watch","test:coverage":"jest --coverage"},"_npmUser":{"name":"principal-ai","email":"principle@principlemd.com"},"repository":{"url":"git+https://github.com/a24z-ai/principal.md.git","type":"git"},"_npmVersion":"10.9.2","description":"Standalone Principal MD MCP server for markdown visualization","directories":{},"_nodeVersion":"23.11.0","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.0.4"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.5.0","ts-jest":"^29.1.0","typescript":"^5.6.3","@types/jest":"^29.5.0","@types/node":"^22.15.26","semantic-release":"^24.2.7","@semantic-release/git":"^10.0.1","@semantic-release/changelog":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/principal-md_0.2.0_1755741795313_0.26556234065085693","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@a24z/principal-md","version":"0.2.1","keywords":["mcp","model-context-protocol","markdown","visualization","principal"],"author":{"name":"a24z Team"},"license":"MIT","_id":"@a24z/principal-md@0.2.1","maintainers":[{"name":"principal-ai","email":"principle@principlemd.com"}],"homepage":"https://a24z.ai","bugs":{"url":"https://github.com/a24z-ai/principal.md/issues"},"bin":{"principal-md":"dist/cli.js"},"dist":{"shasum":"24f9d4d6264e89050a75e5a6d629e5f99d0ea0e1","tarball":"https://registry.npmjs.org/@a24z/principal-md/-/principal-md-0.2.1.tgz","fileCount":27,"integrity":"sha512-q/myJDUCbh4HzCcQLn1PDCFWa5N4fObu1SdVqqUuTqxK6h64PonP3apiYi3fAQFvGlngBnztC4rXraVE2LJ/hQ==","signatures":[{"sig":"MEQCIDwtop5knsIJAEvOI8TktvpiHOk3JCJwZQkgLXp4Jd1WAiBJH9SRPMHPvEe7IqH0hQxbezUihYYT9r0vUpOgC3H1zw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":45474},"main":"dist/lib.js","types":"dist/lib.d.ts","engines":{"node":">=18"},"gitHead":"9cde7e501e950b6c8ce24e784968498f6c4406e7","private":false,"scripts":{"test":"jest","build":"tsc","prepare":"npm run build","release":"semantic-release","postbuild":"chmod +x dist/cli.js","test:watch":"jest --watch","test:coverage":"jest --coverage"},"_npmUser":{"name":"principal-ai","email":"principle@principlemd.com"},"repository":{"url":"git+https://github.com/a24z-ai/principal.md.git","type":"git"},"_npmVersion":"10.9.2","description":"Standalone MCP server for markdown visualization with Memory Palace VS Code extension","directories":{},"_nodeVersion":"23.11.0","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.0.4"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.5.0","ts-jest":"^29.1.0","typescript":"^5.6.3","@types/jest":"^29.5.0","@types/node":"^22.15.26","semantic-release":"^24.2.7","@semantic-release/git":"^10.0.1","@semantic-release/changelog":"^6.0.3"},"_npmOperationalInternal":{"tmp":"tmp/principal-md_0.2.1_1755769014251_0.6817614380208374","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-08-21T00:31:39.864Z","modified":"2026-05-22T04:39:26.725Z","0.1.0":"2025-08-21T00:31:40.142Z","0.1.1":"2025-08-21T00:38:16.761Z","0.2.0":"2025-08-21T02:03:15.524Z","0.2.1":"2025-08-21T09:36:54.438Z"},"bugs":{"url":"https://github.com/a24z-ai/principal.md/issues"},"author":{"name":"a24z Team"},"license":"MIT","homepage":"https://a24z.ai","keywords":["mcp","model-context-protocol","markdown","visualization","principal"],"repository":{"url":"git+https://github.com/a24z-ai/principal.md.git","type":"git"},"description":"Standalone MCP server for markdown visualization with Memory Palace VS Code extension","maintainers":[{"email":"principle@principlemd.com","name":"fernando-ram-lugo"}],"readme":"# Principal MD MCP Server\n\nA standalone MCP (Model Context Protocol) server that enables AI assistants to display and manipulate markdown content in VS Code through the Memory Palace extension.\n\n## Features\n\n- **Display Markdown Content**: Show formatted markdown in VS Code's Industrial Markdown view\n- **Open Markdown Files**: Open specific markdown files with optional line navigation\n- **Bridge Communication**: Seamless integration with VS Code extension via HTTP bridge\n\n## Installation\n\n```bash\nnpm install -g @a24z/principal-md\n```\n\nOr use directly with npx:\n\n```bash\nnpx @a24z/principal-md\n```\n\n## Quick Setup\n\nFor some editors, you can run the following commands for a one-click install:\n\n**Cursor:**\n\n[Install MCP Server](https://cursor.com/settings/mcp)\n\n**Manual Integration**\n\n```json\n{\n  \"mcpServers\": {\n    \"principal-md\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@a24z/principal-md\"\n      ],\n      \"env\": {\n        \"VSCODE_MCP_BRIDGE_PORT\": \"37123\",\n        \"VSCODE_MCP_BRIDGE_HOST\": \"127.0.0.1\"\n      }\n    }\n  }\n}\n```\n\n**For Custom Ports:**\n\n```json\n{\n  \"mcpServers\": {\n    \"principal-md\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@a24z/principal-md\",\n        \"--port\",\n        \"8080\"\n      ],\n      \"env\": {\n        \"VSCODE_MCP_BRIDGE_PORT\": \"8080\",\n        \"VSCODE_MCP_BRIDGE_HOST\": \"127.0.0.1\"\n      }\n    }\n  }\n}\n```\n\n**Jules**\n\nRefer to [Jules MCP configuration](https://docs.jules.sh/mcp); define a server named `principal-md` with the same command, args, and env.\n\n### Automated Installation\n\n#### For Claude Desktop\n\n```bash\n# Install with default port\nprincipal-md install-claude\n\n# Install with custom port\nprincipal-md install-claude --port 8080\n```\n\nThis will add the MCP server configuration to your Claude Desktop settings.\n\n#### For Cursor\n\n```bash\n# Install with default port\nprincipal-md install-cursor\n\n# Install with custom port and host\nprincipal-md install-cursor --port 8080 --host localhost\n```\n\nThis will add the MCP server configuration to your Cursor settings.\n\n## Prerequisites\n\n1. **VS Code Memory Palace Extension**: Install and run the Memory Palace extension in VS Code\n2. **HTTP Bridge**: Ensure the extension's HTTP bridge is running (default port: 37123)\n\n## Usage\n\n### As a Standalone Server\n\n```bash\n# Start the MCP server (default port 37123)\nprincipal-md start\n\n# Start with custom port\nprincipal-md start --port 8080\n\n# Start with custom host and port\nprincipal-md start --host localhost --port 4000\n\n# Using environment variables\nVSCODE_MCP_BRIDGE_PORT=37124 principal-md start\n```\n\n### As a Library\n\n```typescript\nimport { McpServer } from '@a24z/principal-md';\n\nconst server = new McpServer({\n  name: 'principal-md',\n  version: '0.1.0',\n  bridgePort: 37123,\n  bridgeHost: '127.0.0.1'\n});\n\nawait server.start();\n```\n\n## Available Tools\n\n### showMarkdownContent\n\nDisplay markdown content in VS Code:\n\n```json\n{\n  \"content\": \"# Hello World\\nThis is markdown content\",\n  \"title\": \"My Document\",\n  \"metadata\": {}\n}\n```\n\n### openMarkdownFile\n\nOpen a markdown file in VS Code:\n\n```json\n{\n  \"filePath\": \"/path/to/document.md\",\n  \"lineNumber\": 10\n}\n```\n\n### getAppInfo\n\nGet information about the extension and bridge status.\n\n## Environment Variables\n\n- `VSCODE_MCP_BRIDGE_HOST`: Bridge host address (default: `127.0.0.1`)\n- `VSCODE_MCP_BRIDGE_PORT`: Bridge port (default: `37123`)\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/a24z-ai/principal.md.git\ncd principal.md\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Run tests\nnpm test\n```\n\n## Architecture\n\n```\nAI Assistant → MCP Server (stdio) → HTTP Bridge → VS Code Extension → Markdown View\n```\n\n1. AI assistant calls MCP tool (e.g., `showMarkdownContent`)\n2. MCP server receives the call via stdio protocol\n3. Server makes HTTP POST to the bridge endpoint\n4. VS Code extension receives and processes the request\n5. Content appears in VS Code's markdown view\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Creating Custom UI Implementations\n\nThe principal-md MCP server is designed to work with any UI that implements the HTTP bridge protocol. Here's how to create your own UI implementation:\n\n### 1. HTTP Bridge Requirements\n\nYour UI needs to implement an HTTP server with these endpoints:\n\n```typescript\n// GET /health - Health check endpoint\napp.get('/health', (req, res) => {\n  res.json({ \n    status: 'ok', \n    service: 'Your UI Name',\n    version: '1.0.0'\n  });\n});\n\n// POST /show-markdown - Display markdown content\napp.post('/show-markdown', (req, res) => {\n  const { content, title, metadata } = req.body;\n  // Display the markdown content in your UI\n  res.json({ success: true, message: 'Content displayed' });\n});\n\n// POST /open-markdown-file - Open a markdown file\napp.post('/open-markdown-file', (req, res) => {\n  const { filePath, lineNumber } = req.body;\n  // Open the file in your UI\n  res.json({ success: true, message: 'File opened' });\n});\n```\n\n### 2. Using Custom Ports\n\nStart your UI's HTTP bridge on any available port, then configure the MCP server:\n\n```bash\n# Start MCP server with custom port\nprincipal-md start --port 8080\n\n# Install with custom configuration\nprincipal-md install-claude --port 8080 --host localhost\n```\n\n### 3. Example Implementations\n\n- **VS Code Extension**: See [Memory Palace VS Code extension](https://github.com/a24z-ai/principal.md)\n- **Web UI**: Create an Express.js server with the required endpoints\n- **Desktop App**: Use Electron, Tauri, or similar with embedded HTTP server\n- **Terminal UI**: Use a lightweight HTTP server to bridge to terminal-based markdown viewers\n\n## Support\n\nFor issues and questions, please visit [GitHub Issues](https://github.com/a24z-ai/principal.md/issues).","readmeFilename":"README.md"}