MCP Home

mcp之家

一个供家庭使用的小型TypeScript MCP服务器，它公开了相同的只读工具：

• stdio 面向本地客户
• 用于远程客户端和API集成的流式HTTP

该项目针对的是带有Docker Desktop和Plex的家庭Windows机器，但MCP服务器本身保持只读，可以与以下设备干净地工作：

• 本地Claude兼容客户端 stdio
• 远程OAuth保护的MCP上的ChatGPT
• 通过Streamable HTTP传输您自己的应用程序

你得到了什么

• 与两者共享一个工具注册表 stdio 以及HTTP传输
• Docker Desktop、Plex和Corsair iCUE状态的Windows主机刷新脚本
• Windows服务、计划任务、事件日志、SMB共享和主机快照中的侦听端口可见性
• 来自同一主机快照的存储、备份、备份目标、端点健康状况、互联网健康状况、Tailscale、家庭助理和公共暴露摘要
• 快照新鲜度报告、运行历史记录和过时数据建议
• 主页、主机、Docker、笔记、Plex、文件、存储库的自然语言入口点，以及指导下的下一步检查建议
• 可搜索的导出Plex库索引和实时Plex活动快照
• 针对CPU、内存、磁盘和网络适配器的更丰富的Windows主机遥测
• 对端口映射、暴露分类、挂载、重启模式和分流审查进行更深入的Docker检查
• 允许使用搜索、最近文件视图、存储文本预览和文件夹摘要进行文件索引
• 使用脏状态、分支、远程和最近活动报告的本地git repo索引
• 注意和仪表板报告，将过时的快照、Docker问题、停止的服务、失败的任务和脏的存储库滚动到一个视图中
• 拆分工具配置文件，使远程HTTP保持较窄的范围，而本地stdio保持较宽的范围
• 对ChatGPT的OAuth支持和对通用远程客户端的承载令牌支持
• Docker、Caddy和Tailscale部署选项
• 审核日志记录以及烟雾、故障路径、Pester和生产验证脚本

工具组

• 发现：

- list_home_commands - list_docker_commands - list_plex_commands - list_windows_commands - list_file_commands - list_repo_commands - find_home - find_docker - find_host - find_notes - find_plex

• 快照和仪表板：

- get_snapshot_status - get_snapshot_history - get_snapshot_recommendations - get_operations_dashboard - get_attention_report - get_daily_digest - recommend_next_checks - explain_issue - summarize_system_state

• 主持人和备注：

- ping - get_time - get_homelab_status - get_host_status - get_host_resources - list_host_disks - get_host_network_summary - get_storage_health - find_low_space_locations - list_large_folders - get_backup_status - get_backup_target_health - find_failed_backups - check_endpoint_health - get_dns_summary - get_internet_health - get_tailscale_status - get_public_exposure_summary - list_windows_services - get_windows_service_details - get_windows_service_issues - get_windows_event_summary - search_windows_events - find_recent_service_failures - list_scheduled_tasks - get_scheduled_task_details - find_failed_tasks - list_listening_ports - get_share_status - get_home_assistant_status - search_files - list_recent_files - read_text_file - summarize_folder - list_local_repos - get_repo_status - get_recent_repo_activity - list_notes - search_notes - read_note

• Docker：

- 容器状态、项目、映像、网络、卷、清理候选对象、最近的活动、资源使用情况、端口映射、暴露报告、装载报告、重启报告和分流摘要

• Plex：

- 库发现、标题搜索、自然查找、节目和季节摘要、最新添加、甲板上和继续观看数据、未观看的报告和重复检测

对于自然请求：

• 从...开始 find_home 当您不确定答案是否存在于Plex、Docker、主机、文件、存储库、笔记或家庭实验室数据中时
• 从...开始 find_host 对于Windows计算机问题，如 memory, C:, ethernet, tailscale, backup，或 32400
• 从...开始 find_plex 对于Plex的首次查找，例如 Sopranos, Sopranos season 2，或 Pine Barrens
• 使用 summarize_system_state 当您需要一个顶级主机、Docker、Plex、存储、备份和公开汇总时
• 使用 get_daily_digest 当你想要最短的“发生了什么变化，需要注意什么”版本
• 使用 recommend_next_checks 当你知道问题区域，但想要最快的下一个命令候选名单时
• 使用 explain_issue 当您希望将当前快照信号转换为快速操作解释时
• 使用 get_snapshot_status 当结果显得陈旧或不一致时
• 使用 get_snapshot_recommendations 当您需要过时或不完整数据的可能原因时

刀具轮廓

服务器现在支持两个工具配置文件：

• full

供当地和私人使用。这包括笔记、家庭实验室状态、主机详细信息、更深入的Docker检查和完整的只读工具界面。

• public-safe

用于远程HTTP路径。这保留了高价值的只读Plex和Docker状态工具，但省略了更多私有或基础设施详细的工具，如笔记、家庭实验室、主机详细信息、Docker挂载检查和低级容器清单。

默认值：

• HTTP使用 public-safe
• stdio使用 full

环境变量：

MCP_HTTP_TOOL_PROFILE=public-safe
MCP_STDIO_TOOL_PROFILE=full

您还可以用以下命令覆盖两者 MCP_TOOL_PROFILE，但当您希望ChatGPT看到比本地工具更窄的表面时，每传输变量是更好的选择。

快速开始

1. 安装依赖项：

   npm install

1. 复制环境文件：

   Copy-Item .env.example .env

1. 如果您需要Docker、Plex或Windows主机工具，请刷新本地快照：

   npm run refresh:host

1. 可选但建议：安装Windows定时刷新，使快照保持最新：

   npm run schedule:host-refresh

1. 先选择你关心的道路：

- 仅限本地客户： 跑 npm run build，然后使用 node dist/index-stdio.js 或此README中的Claude设置。 - 本地HTTP验证： 跑 npm run dev:http那么 npm run smoke:http默认情况下，这将使用 public-safe HTTP配置文件。 - OAuth上的ChatGPT： 使用Tailscale+Caddy路径，然后在ChatGPT Developer模式下连接已发布的MCP URL。

先决条件

• Node.js 22+
• 如果您希望主机刷新脚本与提供的完全一致，请使用Windows 11
• Python 3，如果你想从本地SQLite数据库导出Plex库
• Docker桌面，如果你想要容器感知工具
• 如果您想要推荐的公共部署路径，请使用Tailscale

为什么这个形状

服务器将工具逻辑保存在一个共享注册表中，并在其上添加两个精简传输。这可以让你：

• 使用本地 stdio 与Claude兼容的本地客户端的入口点
• 使用远程HTTP端点进行OpenAI和Anthropic API集成
• 避免重复工具定义或在客户端之间漂移行为

项目布局

mcp-home/
  data/
    local/
  notes/
  scripts/
  state/
  src/
    core/
    transports/
    index-http.ts
    index-stdio.ts
  Caddyfile
  docker-compose.yml
  Dockerfile

当地开发和验证

1. 安装依赖项：

   npm install

1. 复制环境文件：

   Copy-Item .env.example .env

1. 启动本地stdio服务器：

   npm run dev:stdio

1. 或者启动HTTP服务器：

   npm run dev:http

1. 检查运行状况端点：

   Invoke-RestMethod http://localhost:8787/health

1. 在HTTP服务器运行时运行内置的HTTP烟雾测试：

   npm run smoke:http

烟雾测试现在按以下顺序自动检测第一个健康目标：

- MCP_HEALTH_URL 如果你设置它 - 本地应用HTTP打开 127.0.0.1:${PORT} - 本地Caddy/Tailscale HTTP打开 127.0.0.1:8788 - 起源于 MCP_SERVER_URL

1. 当您想要一个仍在OAuth模式下工作的传输无关工具检查时，请运行stdio烟雾测试：

   npm run smoke:stdio

1. 当服务器已经启动时，运行生产验证包：

   npm run verify:prod

verify:prod 现在运行：

- npm run build - npm run typecheck:scripts - npm run verify:error-paths - npm run smoke:stdio - npm run smoke:stdio:public-safe - npm run smoke:http

1. 更改Windows刷新脚本时运行PowerShell辅助回归套件：

   npm run test:pester

该仓库目前附带了50个Pester测试，涵盖刷新脚本路径解析、事件助手、备份目标检测、Tailscale解析、Docker助手逻辑和Plex/git助手转换。

1. 当您想在不运行整个烟雾包的情况下验证损坏的快照处理和无效的HTTP配置时，只运行故障路径回归检查：

   npm run verify:error-paths

这目前验证了：

- homelab、文件目录、Plex库、Plex活动、仓库状态、快照状态和Windows主机快照读取器的JSON处理格式错误 - 因无效而拒绝启动 PORT HTTP传输中的值

如果你只想要当地的克劳德或其他当地人 stdio 客户，你可以停在这里。该本地路径不需要Caddy、Tailscale、ChatGPT OAuth或单独的API密钥。

如果你想为自己的局域网或尾网使用一个私有的全表面HTTP服务器，请设置：

MCP_HTTP_TOOL_PROFILE=full

Windows主机刷新

Docker容器无法直接看到Windows服务、计划任务、打开的侦听端口、本地存储库、iCUE或Plex，因此存储库现在使用主机端刷新步骤，将只读JSON快照写入 data/local/.

每当您需要新的系统和Plex数据时，请在Windows主机上运行此程序：

npm run refresh:host

该脚本：

• 采用轻量级锁，因此重叠的刷新运行不会相互干扰
• 以原子方式写入快照文件，以减少半写或部分更新的数据
• 读取Windows正常运行时间以及Docker Desktop、Corsair iCUE和Plex进程或服务状态
• 捕获Windows CPU负载、内存使用、磁盘容量和网络适配器遥测
• 捕获Windows服务状态、计划任务状态和侦听TCP或UDP端口
• 从以下位置捕获只读Docker快照 docker ps -a, docker inspect, docker stats --no-stream, docker image ls, docker network ls, docker volume ls，以及 docker system df
• 构建一个包含存储预览的分配文件目录，以进行安全的文本搜索
• 使用分支、远程、脏计数和上次提交活动构建本地git repo状态快照
• 在以下位置探测本地Plex服务器 http://127.0.0.1:32400/identity
• 从本地Plex SQLite数据库导出可搜索的Plex库索引
• 当本地令牌可用时，从本地会话中捕获Plex活动快照，查看历史记录，继续查看中心、平台上中心和未监视的库部分
• 写一个新鲜度和调度程序摘要，MCP服务器稍后可以读回
• 保留滚动快照刷新历史记录，以便您可以查看故障是一次性的还是重复的
• 写道：

- data/local/snapshot-status.json - data/local/snapshot-history.json - data/local/windows-host-status.json - data/local/file-catalog.json - data/local/repo-status.json - data/local/plex-library-index.json - data/local/plex-activity.json

当前的实现要求Windows主机上的Python 3用于Plex数据库导出。MCP服务器保持只读，只读取生成的JSON文件。

重要提示：PowerShell刷新脚本现在也读取 .env 在解析快照设置之前。这意味着存储扫描根、备份关键字、端点检查、Tailscale路径覆盖、文件根和仓库根都可以存在 .env 而不需要先在shell中手动导出。

刷新主机数据后，这些工具变得有用：

• list_home_commands
• get_snapshot_status
• get_snapshot_history
• get_snapshot_recommendations
• get_operations_dashboard
• get_attention_report
• get_daily_digest
• summarize_system_state
• find_home
• find_host
• find_docker
• find_notes
• list_windows_commands
• list_file_commands
• list_repo_commands
• list_docker_commands
• get_host_status
• get_host_resources
• list_host_disks
• get_host_network_summary
• get_storage_health
• find_low_space_locations
• list_large_folders
• get_backup_status
• find_failed_backups
• check_endpoint_health
• get_dns_summary
• get_tailscale_status
• get_public_exposure_summary
• list_windows_services
• get_windows_service_details
• get_windows_service_issues
• list_scheduled_tasks
• get_scheduled_task_details
• find_failed_tasks
• list_listening_ports
• search_files
• list_recent_files
• read_text_file
• summarize_folder
• list_local_repos
• get_repo_status
• get_recent_repo_activity
• get_docker_exposure_report
• get_docker_triage_report
• get_docker_status
• list_docker_containers
• get_docker_projects
• get_docker_issues
• get_docker_container_details
• list_docker_images
• list_docker_networks
• get_docker_resource_usage
• get_docker_recent_activity
• get_docker_compose_health
• get_docker_project_details
• list_docker_volumes
• get_docker_cleanup_candidates
• get_docker_port_map
• get_docker_mount_report
• get_docker_restart_report
• list_plex_commands
• find_plex
• get_plex_status
• get_plex_server_activity
• get_plex_now_playing
• get_plex_recently_watched
• get_plex_continue_watching
• get_plex_on_deck
• find_plex_unwatched
• get_plex_item_details
• browse_plex_by_genre
• browse_plex_by_decade
• get_plex_library_stats
• get_plex_show_summary
• get_plex_season_summary
• get_recently_aired_episodes
• find_plex_series_gaps
• list_plex_sections
• browse_plex_show_episodes
• browse_plex_children
• find_plex_episode
• search_plex_library
• search_plex_titles
• list_plex_duplicates
• get_recent_plex_additions

自动刷新Windows

如果您希望主机和Plex快照在不手动运行命令的情况下保持新鲜，那么该仓库现在包含了Windows任务计划程序的帮助脚本。

以默认的30分钟间隔安装重复任务：

npm run schedule:host-refresh

稍后删除：

npm run unschedule:host-refresh

如果需要不同的间隔，请直接运行PowerShell脚本：

powershell -ExecutionPolicy Bypass -File scripts/install-host-refresh-task.ps1 -IntervalMinutes 15

这将创建一个名为的用户级计划任务 MCP Home Host Refresh 运行 scripts/refresh-windows-host.ps1.

计划任务使用隐藏的PowerShell窗口，以及 get_snapshot_status 加 get_snapshot_history 将告诉您任务是否已安装、上次运行时间以及刷新失败是否重复。

新鲜感和自然语言入口点

如果服务器在测试过程中感觉过时，请从以下步骤开始：

get_snapshot_status

然后执行以下操作：

get_snapshot_recommendations

该报告指出：

• 上次主机刷新是否成功完成
• 是否安装了计划任务
• 每个快照的年龄
• 每个快照是否 fresh, late, stale，或丢失

get_snapshot_history 添加了最近的运行时间线，当您试图将一次性刷新失败与反复出现的主机端故障分开时，这尤其有用。

对于日常使用，这些是最简单的入口点：

• find_home 用于跨域查找
• find_host 针对Windows CPU、内存、磁盘、适配器、服务、任务和端口问题
• find_docker 用于容器、项目、图像、网络和卷
• find_notes 当地降价笔记
• find_plex Plex首次搜索
• summarize_system_state 用于最短的单系统汇总
• get_daily_digest 最简短的“发生了什么变化，需要跟进什么”观点
• get_operations_dashboard 快速操作概述
• get_attention_report 当你想要最短的需要跟进的事情列表时

在远程HTTP路径上， find_home 将保留在活动配置文件暴露的工具内。默认情况下 public-safe 配置文件，这意味着Plex和Docker，而不是笔记或家庭实验室内容。

文件和仓库索引

新的文件和仓库工具仍然是只读的，但它们依赖于显式的快照输入，因此服务器永远不会在请求时抓取任意路径。

有用的 .env 设置：

FILE_INDEX_ROOTS=./notes
FILE_INDEX_TEXT_EXTENSIONS=.md,.txt,.json,.yaml,.yml,.log,.ps1,.ts,.js,.tsx,.jsx
FILE_INDEX_MAX_FILES=500
FILE_INDEX_PREVIEW_CHARS=2000
REPO_SCAN_ROOTS=.
REPO_SCAN_MAX_DEPTH=4
STORAGE_SCAN_ROOTS=.
STORAGE_SCAN_CHILD_LIMIT=15
STORAGE_LOW_SPACE_PERCENT=15
BACKUP_TASK_KEYWORDS=backup,file history,filehistory,regidlebackup,veeam,archive,robocopy,clone
BACKUP_STALE_HOURS=48
NETWORK_ENDPOINT_CHECKS=
NETWORK_CHECK_TIMEOUT_SECONDS=5
TAILSCALE_EXE=
MCP_HEALTH_URL=

默认值是保守的：

• 文件索引以开头 ./notes
• 回购扫描从当前回购根开始
• 两个输出仅在以下期间刷新 npm run refresh:host

如果你拓宽了这些根，就要有意识地保持它们。重点是一个有用的跨列表，而不是广泛的文件系统公开。

笔记：

• STORAGE_SCAN_ROOTS 控制扫描哪些文件夹以查找大文件夹和低空间报告。
• BACKUP_TASK_KEYWORDS 控制哪些计划任务算作与备份相关的任务。
• NETWORK_ENDPOINT_CHECKS 在刷新步骤中添加额外的端点探测。将其留空，仅保留内置默认值。
• TAILSCALE_EXE 仅当Tailscale安装在Windows上的非标准位置时才需要。
• MCP_HEALTH_URL 是可选的，用于主机刷新和烟雾测试目标选择的首选本地MCP健康目标。

API模型检查

OpenAI和Anthropic无法连接 http://localhost:8787/mcp 直接。在使用API之前，使用Caddy将MCP服务器公开在公共HTTPS URL上，再加上隧道或您自己的域，然后设置 MCP_SERVER_URL 在 .env.

一旦到位：

npm run test:openai:mcp
npm run test:anthropic:mcp

使用OAuth的ChatGPT

如果你想将此服务器连接到ChatGPT，而不让端点未经身份验证，请使用内置的OAuth模式。

在中设置这些值 .env:

MCP_AUTH_MODE=oauth
MCP_SERVER_URL=https://your-public-hostname/mcp
MCP_OAUTH_PASSWORD=your-shared-password
MCP_OAUTH_STATE_PATH=./state/oauth-state.json

如果 MCP_OAUTH_PASSWORD 如果留空，服务器将回退到 MCP_AUTH_TOKEN 作为登录密码。

OAuth客户端注册和令牌现在持久化到 state/ 因此，ChatGPT重新连接在容器重新启动或重建后仍能继续工作。

然后重新启动堆栈并验证本地身份验证元数据：

docker compose -f docker-compose.tailscale.yml up -d --build
npm run smoke:http

当OAuth模式工作时，烟雾测试应显示：

• 成功的 /health 回应
• 受保护的资源元数据URL
• 一 401 上 /mcp 带着一个 WWW-Authenticate 将客户端指向OAuth元数据的标头

之后，重新启用 tailscale funnel 并使用您的公共MCP URL在开发人员模式下从ChatGPT连接应用程序。ChatGPT将打开一个浏览器登录步骤，您可以在其中输入共享密码。

您的反向代理必须公开这些OAuth路由，而不仅仅是 /mcp:

• /.well-known/oauth-protected-resource/mcp
• /.well-known/oauth-authorization-server
• /authorize
• /register
• /token
• /revoke
• /oauth/login

生产抛光注意事项

容器映像现在包括一个内置的健康检查 /health，两个Compose文件都在等待 mcp-home 在开始Caddy之前，先保持健康。这为您提供了一个更可靠的启动路径，用于本地重启、重建和隧道重新连接。

主机刷新路径现在还记录了一个单独的 snapshot-status.json 文件，因此MCP服务器可以告诉您底层Windows、Docker和Plex数据何时过时，而不是从过时的文件中静默应答。

HTTP传输现在也在中报告其活动工具配置文件 /health，这使得在部署后更容易调试“为什么ChatGPT看不到这个工具？”问题。

验证包现在包含显式格式错误的快照和无效快照-PORT 回归检查，因此在发布之前会执行常见的配置错误和JSON错误模式。

推荐远程路径：球童+尾秤漏斗

如果您不想打开路由器端口，这是最干净的家庭设置。

1. 在Windows主机上安装并登录Tailscale。

1. 确保在Tailscale管理控制台中为您的尾网启用了漏斗。

1. 启动本地反向代理堆栈：

   docker compose -f docker-compose.tailscale.yml up --build -d

1. 在发布本地代理之前验证它：

   Invoke-RestMethod http://127.0.0.1:8788/health

1. 尾网内可选择私人干跑：

   tailscale serve --bg http://127.0.0.1:8788
   tailscale serve status

serve 仅为尾网。它对于来自另一台Tailscale设备的私人支票很有用，但OpenAI和Anthropic仍然无法访问它。

1. 通过Tailscale漏斗发布本地Caddy端点：

   tailscale funnel --bg http://127.0.0.1:8788

1. 寻找公众 .ts.net 网址：

   tailscale funnel status

1. 集 MCP_SERVER_URL 在 .env 例如：

   MCP_SERVER_URL=https://your-machine.your-tailnet.ts.net/mcp

1. 运行面向模型的检查：

   npm run test:openai:mcp
   npm run test:anthropic:mcp

此堆栈使Caddy在 127.0.0.1:8788，Tailscale提供公共HTTPS入口点。这意味着没有路由器端口转发，也没有Docker端口直接暴露在局域网中。

克劳德设置

对于可以生成stdio服务器的本地客户端，将它们指向构建的入口点：

npm run build
node dist/index-stdio.js

具体来说，对于Claude Code来说，当前的Anthropic CLI流程是：

claude mcp add --transport stdio mcp-home -- node /absolute/path/to/dist/index-stdio.js

在原生Windows上，Anthropic目前建议包装 npx 命令与 cmd /c，但直接 node 该命令适用于此项目，因为入口点已经是本地脚本。

OpenAI响应API示例

const response = await fetch("https://api.openai.com/v1/responses", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.OPENAI_API_KEY}`
  },
  body: JSON.stringify({
    model: "gpt-5",
    input: "Search my notes for homelab and summarize what you find.",
    tools: [
      {
        type: "mcp",
        server_label: "home",
        server_url: "https://your-domain.example.com/mcp",
        authorization: process.env.MCP_AUTH_TOKEN,
        allowed_tools: ["search_notes", "read_note"],
        require_approval: "never"
      }
    ]
  })
});

console.log(await response.json());

人类信息API示例

截至2026年3月31日，Anthropic的MCP连接器文件要求 anthropic-beta: mcp-client-2025-11-20 头球当前请求形状将连接详细信息保存在 mcp_servers 并通过 mcp_toolset 报关进口 tools.

const resp = await fetch("https://api.anthropic.com/v1/messages", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "x-api-key": process.env.ANTHROPIC_API_KEY!,
    "anthropic-version": "2023-06-01",
    "anthropic-beta": "mcp-client-2025-11-20"
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-6",
    max_tokens: 800,
    messages: [
      { role: "user", content: "List my notes and read the homelab one." }
    ],
    mcp_servers: [
      {
        type: "url",
        url: "https://your-domain.example.com/mcp",
        name: "home",
        authorization_token: process.env.MCP_AUTH_TOKEN
      }
    ],
    tools: [
      {
        type: "mcp_toolset",
        mcp_server_name: "home",
        default_config: {
          enabled: false
        },
        configs: {
          list_notes: {
            enabled: true
          },
          read_note: {
            enabled: true
          }
        }
      }
    ]
  })
});

console.log(await resp.json());

Docker和Caddy

集装箱堆叠包括：

• mcp-home 对于HTTP服务器
• caddy 用于HTTPS终止和反向代理

用以下方式提出：

docker compose up --build -d

为了地方发展， .env 使用repo相对路径，如 ./notes 和 ./data/homelab-status.jsonDocker Compose会自动覆盖那些具有容器路径的内容。

使用 docker-compose.yml 当您希望Caddy直接终止您自己域的TLS时。

使用 docker-compose.tailscale.yml 加 Caddyfile.tailscale 当您希望Tailscale漏斗提供公共HTTPS URL时。

故障排除

• npm run smoke:http 击中了错误的目标

烟雾脚本尝试 MCP_HEALTH_URL那么 127.0.0.1:${PORT}那么 127.0.0.1:8788，则来源于 MCP_SERVER_URL.

• ChatGPT已连接，但未显示最新的工具列表

断开并重新连接应用程序，或删除并重新添加，然后开始新的聊天。

• ChatGPT看不到可以在本地使用的注释或特定于主机的工具

检查活动HTTP配置文件。默认远程配置文件为 public-safe，故意隐藏更多私人工具。使用 list_home_commands 或 /health 以确认暴露的内容。

• Plex或Docker工具返回过时数据

跑 npm run refresh:host 在Windows主机上，然后使用 get_snapshot_status 和 get_snapshot_recommendations 确认新鲜度并查看可能的原因。如果快照一直过时，请安装计划刷新任务。

• 文件搜索或存储库工具显示旧结果

跑 npm run refresh:host，然后检查 get_snapshot_status 为了 fileCatalog 和 repoStatus 条目。如果这些仍然陈旧，请确认 FILE_INDEX_ROOTS 和 REPO_SCAN_ROOTS 被设置为真正可读的路径。

• tailscale 在PowerShell中无法识别

例如，使用完整的可执行路径 C:\Program Files\Tailscale\tailscale.exe，或将Tailscale添加到 PATH.

• 即使ChatGPT工作，OpenAI或Anthropic测试也会失败

ChatGPT订阅和API计费是分开的。 npm run test:openai:mcp 和 npm run test:anthropic:mcp 需要真正的API密钥和可公开访问的MCP URL。

• Docker或Caddy已启动，但堆栈尚未就绪

检查 docker ps 等待 mcp-home 成为 healthy 在测试公共端点之前。

• 主机刷新看起来很健康，但结果似乎仍然很旧

snapshot-status.json, snapshot-history.json, get_snapshot_status，以及 get_snapshot_recommendations 将显示三个快照文件中是否只有一个滞后，或者刷新是否反复失败，这在缺少Plex导出先决条件时很常见。

安全注意事项

保持此服务器只读，直到您信任部署路径和日志记录。

• 使用长随机承载令牌。
• 保持 allowed_tools 在每个远程API调用上都很窄。
• 更喜欢比本地工具配置文件更窄的远程工具配置文件。
• 不要将shell、SSH、Docker控件或文件写入与广泛的只读工具暴露在同一服务器上。
• 与原始路由器端口转发相比，更喜欢Tailscale或Cloudflare隧道。
• 将主机生成的快照保存在 data/local/ 脱离版本控制。它们可以显示本地库名称和机器详细信息。

公共共享清单

在将存储库从私有切换到公共之前：

• 确认 .env, data/local/, logs/，OAuth状态文件仍然被忽略
• 轮换任何曾经在本地使用过的真实令牌或密码，即使它们后来被删除
• 健全性检查 README.md、示例注释，以及 data/homelab-status.json 对于任何你不想公开索引的东西
• 确认已包含 LICENSE 匹配您希望其他人如何重用该项目

下一步

好的下一个补充：

• 按工具身份验证策略
• 用于高风险工具的单独的仅限管理员的MCP服务器
• 更丰富的Plex元数据，如演员、导演、叙述者和收藏
• 如果您需要CPU、内存、磁盘或UPS特定的仪表板，则可以进行更广泛的主机遥测

审核日志记录

工具调用现在被审计记录为JSON行，包括：

• 时间戳
• 工具名称
• 成败
• 持续时间（毫秒）
• 经过净化的简短论点总结

默认情况下，审计记录会写入stderr，如果 MCP_AUDIT_LOG_PATH 设置为JSONL附加到该文件。

例子：

{"timestamp":"2026-03-31T16:00:00.000Z","event":"tool_call","tool":"read_note","ok":true,"durationMs":12,"argSummary":"slug=\"homelab\""}

敏感参数名称，如 token, secret, password, authorization, cookie，以及 key 会自动编辑。

参考文献

• OpenAI远程MCP指南：https://platform.openai.com/docs/guides/tools-remote-mcp
• OpenAI MCP服务器指南：https://platform.openai.com/docs/mcp
• 拟人MCP连接器：https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector
• 人类克劳德代码MCP指南：https://docs.anthropic.com/en/docs/claude-code/mcp
• MCP运输规范：https://modelcontextprotocol.io/specification/2025-11-25/basic/transports