Mrdj App MCP

麦鸿崧先生

这是在我的VPS上运行的，可以在任何客户端使用，如VS Code davidjgrimsley.com/public-facing/mcp/mrdj-app-mcp/mcp。有一个更深入的信息页面 Davidjgrimsley.com/mcp/mrdj-assis.

模型上下文协议（MCP）服务器，将我的Expo/React Native网络和移动指南（PokePages）作为结构化资源呈现。构建为在本地或反向代理（例如Plesk）后面运行，因此AI工具可以查询我使用的相同文档。

技术栈

• TypeScript+Node.js（ES模块）
• @modelcontextprotocol/sdk 1.25.x
• 轻量级构建方式 tsc；单一入口点 build/index.js
• 基于文件的内容 guides/ 打包为MCP资源
• Plesk友好：无原生deps，静态构建输出；也可以托管在任何支持Node的平台或容器上

本MCP涵盖了什么，并假设您正在使用（以文档为指导）

• 架构模式：Expo应用程序布局、模块边界、路由与屏幕。
• 状态管理：Zustand存储模式、选择器、持久性。
• 数据：Drizzle ORM+Supabase模式指导、RLS、迁移、种子/固定装置。
• 样式：UniWind设置、CSS中的标记/主题、响应/主题方法（此MCP最初支持NativeWind）。
• 路由：Expo Router约定、基于文件的路由、保护、深度链接。
• 动画：重新激活了4个指导（小作品、过渡、线程分离）。
• 性能和搜索引擎优化：启动、重新执行器控制、列表调优、编译器提示、元数据。
• 构建脚本：本地构建/导出脚本，网站地图生成，API构建。
• 部署：请参阅静态web和API的部署说明，以及反向代理配合。

文档查找工具

此MCP包括用于在聊天/代码审查期间快速查找文档的轻量级工具：

• smart-help 自动选择相关指南+文档源并进行搜索（推荐）
• list-docs 按id列出已知文档源
• search-docs 按id+查询搜索这些文档（无URL复制/粘贴）
• fetch-web-doc 获取/搜索任意文档URL（回退）

项目审计/转换工具

项目背景（业务+风格）

将高级项目意图和样式标记存储在顶级项目/文件夹中：

• project/info.md（业务目标、受众、成果、应用类型）
• project/style.md（字体、颜色代码、间距、组件色调）

生成项目说明工具读取这些文件（如果需要，可以回退到project/info.txt和project/style.txt），并将它们与指南合并到.github/copilot-instructions.md中。

生成项目todo工具从project/info.md+project/style.md构建项目/TOO.md。它提取：

• 特征、流和实体 来自project/info.md
• 风格标记 （颜色、字体、间距）来自project/style.md
• 导航模式 （标签、抽屉、堆栈或混合）从项目描述中推断出来
• 建议的文件结构 （src/app/layout，包含_layout.tsx文件、功能组、身份验证等）

这有助于您从第一天开始就制定一个全面的计划来启动开发，包括设计系统工作+路线框架。

项目接收+完整构建提示

• ingest-project-context 默认情况下，将project/info.txt+project/style.txt转换为markdown并删除.txt文件。
• 提示 project-intake 运行摄取，生成project/TOO.md，然后重新生成副驾驶指令。
• 提示 full-app-build 总结上下文，提出一次澄清问题，然后在回答后自动启动任务（当存在时引用project/TOO.md）。

convert-styling （Uniwind）

扫描目标项目的造型使用情况，并将其与当地的Uniwind造型指南进行核对(guides/styling.md).

它还可以应用一小部分 安全、机械 迁移步骤（默认情况下为模拟运行）：

• 去除 nativewind/babel 从 babel.config.* （尽最大努力）
• 尽力更新 metro.config.* 来自NativeWind→ Uniwind命名
• 正常化 global.css 到Tailwind 4+Uniwind进口(@import 'tailwindcss'; 和 @import 'uniwind';)
• 删除 nativewind.d.ts （当 apply=true)

它也将 *报告* （但不自动转换）通常需要手动编辑的项目：

• StyleSheet.create() 用法
• 运行时NativeWind API(ThemeProvider, cssInterop, styled等等）
• 非平凡的Tailwind/NativeWind配置迁移

内存模式（“添加文件到聊天”）

一些MCP客户端（包括VS Code）可以将文件附加到聊天上下文中，但MCP服务器进程可能无法访问您的仓库的文件系统（特别是在使用远程HTTP/SSE服务器时）。

为了支持该工作流程， convert-styling 还接受内存中的 files 数组：

• files: [{ path, content }] （路径只是一个标签；相对工作空间是理想的）
• basePath：可选标签（例如回购名称）

当 files 提供：

• projectRoot 被忽略
• apply=true 返回一个编辑包（它不会写入磁盘）

这最适合转换您附加到聊天的少数文件。由于消息大小的限制，对于整个回购迁移来说是不切实际的。

如何使用工具

这些是此服务器公开的MCP工具。在启用MCP的聊天客户端（VS Code Copilot chat等）中，您通常不会直接“运行命令”，而是要求助手使用特定输入调用该工具。

注意：您的MCP客户端可以选择何时自动调用工具。如果你想每次都使用“自动模式”，请使用 smart-help 作为唯一的入口点。

常见工作流程

0）自动模式（推荐）

• 让助手跑 smart-help 你的问题。
• 例如：“运行智能帮助，回答以下问题：‘我们应该如何为身份验证门控构建Expo Router布局？’”
• 它将：

- 在中选择相关指南 guides/ - 查询最相关的实时文档来源 - 返回指南摘录+文档片段

1） 查找正确的文档id

• 让助手跑 list-docs.
• 选择 docId 你想要（例如。 uniwind, nativewind, expo-router).

2） 在不粘贴URL的情况下搜索这些文档

• 让助手跑 search-docs 与：

- docId：其中一个id来自 list-docs - query：要搜索的关键字/短语 - 可选： maxMatchesPerUrl （默认值5）和 maxUrls （默认：该文档已全部注册）

3） 未注册文档页面的回退

• 让助手跑 fetch-web-doc 与：

- url：任何公众 https://... 文档URL - 可选： query 和 maxMatches

示例提示（复制/粘贴）

• “跑 smart-help 和 question=How do I migrate cssInterop from NativeWind to Uniwind?”
• “跑 smart-help 和 question=What is the right Expo Router layout for auth gating?”
• “跑 list-docs 并向我展示可用的 docIds
• “跑 search-docs 和 docId=uniwind 和 query=ThemeProvider.”
• “跑 search-docs 和 docId=nativewind 和 query=cssInterop （maxUrls=2）。”
• “跑 fetch-web-doc 为了 https://docs.uniwind.dev/migration-from-nativewind 并搜索 rem （最大匹配次数=5）。”
• “跑 convert-styling （干运行） projectRoot=/absolute/path/to/my-app.”
• “跑 convert-styling 和 projectRoot=/absolute/path/to/my-app 和 apply=true.”

选择要扫描的项目

convert-styling 默认扫描：

• MCP_PROJECT_ROOT 如果设置，否则
• 服务器进程工作目录

要在启动服务器时设置默认根目录，请执行以下操作：

• node build/index.js --project-root /absolute/path/to/my-app
• pm2 start build/index.js --name mrdj-app-mcp -- --http-port 4000 --project-root /absolute/path/to/my-app

指南资源与工具

此服务器还公开了Markdown指南 guides/ 作为MCP 资源.

• 使用工具 list-guides 查看可用的指南。
• 然后通过客户的“readResource”流程打开/阅读指南（因客户而异）。

为什么它适合Plesk（及以后）

• 单节点流程，无需额外服务；易于在Plesk的Node支持下运行或作为代理应用程序运行。
• 纯JS输出(build/)；没有二进制文件，因此它可以干净地迁移到其他主机（Docker、裸VM、无服务器HTTP包装器）。
• 配置灯：只需将命令设置为 node build/index.js （或 npm start)如果通过HTTP提供服务，则添加反向代理/路径。

在本地运行（stdio MCP）

1. 安装Node.js 18+。
2. 克隆并安装：

- git clone https://github.com/DavidJGrimsley/mrdj-app-mcp.git - cd mrdj-app-mcp && npm install

1. 构建： npm run build
2. 启动MCP服务器（stdio）： npm start
3. 根据官方指南，将您的MCP兼容客户端指向服务器：https://modelcontextprotocol.io/docs/getting-started/intro

以HTTP/SSE服务器运行（用于远程访问）

服务器支持使用服务器发送事件（SSE）进行远程MCP访问的HTTP传输。

本地测试

npm run build
npm run start:http  # Starts on port 4000
# Test: curl http://localhost:4000/health

VPS部署（例如。， /home/deployer/mrdj-app-mcp)

1.将文件复制到VPS

# From your local machine
scp -r build/ guides/ package*.json deployer@DavidJGrimsley.com:/home/deployer/mrdj-app-mcp/

2.在VPS上安装依赖项

ssh deployer@DavidJGrimsley.com
cd /home/deployer/mrdj-app-mcp
npm ci --production

3.从PM2开始

pm2 start build/index.js --name mrdj-app-mcp -- --http-port 4000
pm2 save
pm2 startup  # Follow instructions to enable on boot

4.配置NGINX反向代理

添加到NGINX站点配置（通常 /etc/nginx/sites-available/yourdomain.com):

# MCP endpoint (Streamable HTTP + SSE)
location /public-facing/mcp/mrdj-app-mcp/mcp {
    proxy_pass http://localhost:4000/mcp;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_cache_bypass $http_upgrade;

    # SSE support - critical for MCP
    proxy_buffering off;
    proxy_read_timeout 86400s;
    proxy_send_timeout 86400s;

    # CORS headers
    add_header Access-Control-Allow-Origin * always;
    add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS' always;
    add_header Access-Control-Allow-Headers 'Content-Type, Authorization' always;
}

# SSE message POST endpoint (required for legacy SSE transport)
location /public-facing/mcp/mrdj-app-mcp/messages {
    proxy_pass http://localhost:4000/mcp/messages;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    
    # Don't buffer - SSE transport needs raw stream
    proxy_buffering off;
    
    add_header Access-Control-Allow-Origin * always;
}

# Health check endpoint
location /public-facing/mcp/mrdj-app-mcp/health {
    proxy_pass http://localhost:4000/health;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
}

重要：The /messages 端点至关重要！使用SSE传输的MCP客户端将向此路径POST消息。没有它，您将看到“无法POST/mcp/messages”错误。

测试和重新加载：

sudo nginx -t
sudo systemctl reload nginx

5.验证部署

# Health check
curl https://yourdomain.com/public-facing/mcp/mrdj-app-mcp/health

# Should return: {"status":"ok","service":"mrdj-app-mcp","version":"0.1.0"}

故障排除

在MCP客户端中使用HTTP端点

配置您的MCP客户端以连接到：

https://yourdomain.com/public-facing/mcp/mrdj-app-mcp/mcp

VS代码示例 （in .vscode/mcp.json 或用户设置）：

{
  "servers": {
    "mrdj-app-mcp": {
      "type": "sse",
      "url": "https://yourdomain.com/public-facing/mcp/mrdj-app-mcp/mcp"
    }
  }
}

服务器提供开放访问（无身份验证），因此任何人都可以在其IDE或MCP兼容工具中使用指南。

项目布局

• src/index.ts --MCP服务器实现
• src/convertStyling.ts --尽力而为的样式审核+Uniwind迁移工具
• build/index.js --编译输出
• guides/ --域指南作为MCP资源公开

贡献

• 打开一个问题或公关，清楚地总结你提出的改变。
• 尽可能保持指南简洁、可操作，并链接来源。
• 跑 npm run build 在推动以确保TypeScript构建保持绿色之前。
• 在讨论中保持尊重；这个项目的存在是为了分享经验。

大声喊叫

感谢那些教学和工具启发了这一切的人：@saimon24、@Galaxies dev、@EvanBacon、@kacperkapusciak、@betomoedano、@expo、@kadikraman。