使用说明

CapCorn酒店MCP服务器

一个专注的Laravel应用程序，通过上游CapCorn API公开了一个用于酒店房间发现和预订的模型上下文协议（MCP）服务器。它的设计简单、安全，易于使用新的MCP工具进行扩展。

关键能力：

搜索可用房间，在一定时间内灵活住宿
查看具体日期的直接房间可用性
使用客人详细信息和价格创建预订

MCP端点：

/mcp/capcorn（网络传输mcp服务器）

快速参考：

路线注册： routes/ai.php
服务器类： CapCornServer类扩展服务器
工具： app/Mcp/CapCornServer/工具/
服务配置： config/services.php
部署指南： docs/DEPLOYMENT-CLOUD-RUN.md
有用的脚本： scripts/run_mcp_tests.sh, scripts/run_cloudrun_checks.sh, scripts/start_mcp_server.sh

清理注意事项

这个项目被精简了。删除了未使用的脚手架：遗留的身份验证用户模型/迁移/工厂、未使用的服务和未使用的邮件。Config/services.php现在只保留capcorn.base_url。

1）架构概述

MCP的HTTP入口点在中声明 routes/ai.php.我们使用Laravel MCP在/MCP/caporn挂载服务器。
服务器类 CapCornServer类扩展服务器定义：
- 受保护字符串$name，受保护字符串$version
- 受保护的字符串$指令（面向LLM的指导）
- protected array$tools：实现实际功能的MCP工具类
每个工具都扩展了Laravel MCP工具并实现了：
- 受保护的字符串$description（显示给LLM）
- 公共函数句柄（Request）：响应（核心逻辑）
- 公共函数模式（JsonSchema）：数组（用于工具调用的强类型参数）

数据流（典型）：

客户端提示LLM
LLM选择一个工具并调用MCP服务器（通过HTTP）
该工具验证/规范输入，通过HTTP调用上游CapCorn API，并格式化人性化的结果（纯文本响应）
LLM向用户展示工具结果，可能链接多个工具

2）当前工具

类SearchRoomsTool扩展工具
- 在给定时间范围内灵活搜索住宿。生成期间中的所有日期范围并对其进行查询。
- 参数包括语言、timespan.from/to、持续时间、成人、儿童[]。
类SearchRoomAvailability工具扩展工具
- 直接提供准确的到达/离开日期和房间组成。
- 参数包括语言（0/1）、到达、离开、房间[*]。
类CreateReservationTool扩展工具
- 使用可用性结果中的room_type_code创建预订，包括客人信息和可选服务。
- 验证客人数量和字段，返回简洁的确认或格式化的错误列表。

3）配置

CapCorn只需要一个配置块：

config/services.php
- capcorn.base_url：所有工具使用的capcorn API的上游HTTP基础。

环境：

CAPCORN-BASE_URL=https://lookingcom-backend.vercel.app
- 在.env中重写以指向上游（本地或远程）。

认证脚手架：

此应用程序不附带运行时用户模型或身份验证路由。如果您稍后添加一个， config/auth.php 仍然通过env（'AUTH_model'）引用模型字符串，即使不存在模型，这也是安全的。

4）本地运行

先决条件：

PHP 8.2+，编辑器，curl

安装：

composer install
cp .env.example .env
php artisan key:generate

启动应用程序：

php artisan serve
# App: http://localhost:8000
# MCP endpoint: http://localhost:8000/mcp/capcorn (MCP over HTTP POST)
# Metadata (JSON): http://localhost:8000/mcp/capcorn/meta

MCP检查员（交互式本地测试）：

php artisan mcp:inspector mcp/capcorn

/mcp/capcorn路径表示mcp（流式HTTP POST）。GET on/mcp/capcorn将返回405（预期）。使用/mcp/caporn/meta-helper查找服务器名称、版本、说明和工具列表。

5）测试和验证

弗拉姆：

php artisan test

端到端MCP验证：

scripts/run_mcp_tests.sh 启动本地服务器（如果需要），执行健全性检查，并在reports/下编写Markdown报告（Git忽略）。

bash scripts/run_mcp_tests.sh
# Output: reports/mcp_report-YYYYMMDD-HHMMSS.md

Cloud Run烟雾检查（远程）：

部署后，您可以执行快速探测：

SERVICE_URL="$(gcloud run services describe mcp-hotel-server \
  --region europe-west1 --format='value(status.url)')"

curl -i "$SERVICE_URL/"
curl -i "$SERVICE_URL/mcp/capcorn/meta"  # MCP metadata (JSON)
# Note: GET "$SERVICE_URL/mcp/capcorn" is expected to return 405

CI检查（本地或模拟CI）：

scripts/run_cloudrun_checks.sh
- Lints仓库结构，并对您的配置和工作流执行一小部分模拟检查。

6）添加新的MCP工具

在app/Mcp/CapCornServer/Tools下创建一个新的Tool类，例如MyNewTool.php：

<?php

namespace App\Mcp\CapCornServer\Tools;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;
use Illuminate\Support\Facades\Http;
use Illuminate\JsonSchema\JsonSchema;

class MyNewTool extends Tool
{
    protected string $description = <<<'MARKDOWN'
        Short summary of what the tool does and when to use it.
    MARKDOWN;

    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'param' => 'required|string',
        ]);

        // Call upstream or implement your logic
        // $baseUrl = config('services.capcorn.base_url');
        // $resp = Http::post($baseUrl.'/api/v1/some-endpoint', [ 'param' => $validated['param'] ]);

        // Return a textual result (MCP transports plain text here)
        return Response::text("Result for {$validated['param']}");
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'param' => $schema->string()->description('Description of param'),
        ];
    }
}

在服务器工具列表中注册 CapCornServer类扩展服务器，通过将您的类添加到受保护的数组$tools中：

protected array $tools = [
    \App\Mcp\CapCornServer\Tools\SearchRoomsTool::class,
    \App\Mcp\CapCornServer\Tools\SearchRoomAvailabilityTool::class,
    \App\Mcp\CapCornServer\Tools\CreateReservationTool::class,
    \App\Mcp\CapCornServer\Tools\MyNewTool::class, // <-- add this line
];

保持工具描述的简洁和有用；确保模式类型与接受的输入匹配。始终使用$request->validate（[…]）验证handle（）中的输入，以保护上游并提供可预测的用户体验。
如果添加新的配置密钥，请将其放置在 config/services.php 并通过配置（'services.capcorn…'）或新的根级服务块读取它们。

7）部署（谷歌云运行）

此仓库包括一个Dockerfile和一个GitHub Actions工作流，该工作流：

构建容器映像
将其推送到工件注册表
使用公共入口将其部署到Cloud Run

工作流程：

deploy-cloudrun.yml
- 需要GitHub机密GCP_SA_KEY（角色为run.admin、artifactregister.writer、iam.serviceAccountUser的GCP服务帐户的JSON）
- 通过JSON secret使用谷歌github actions/auth进行工作负载身份验证

首次设置步骤和完整说明：

docs/DEPLOYMENT-CLOUD-RUN.md

部署后，获取服务URL：

gcloud run services describe mcp-hotel-server \
  --region europe-west1 --format='value(status.url)'

公共端点：

根：GET/（欢迎页面）
MCP服务器元数据：GET/MCP/caporn/meta
MCP:POST/MCP/capcorn（MCP传输；GET按设计返回405）

8）安全说明

切勿提交明文云密钥。存储库忽略.env，现在也忽略gcp-sa-key.json。
将GitHub secrets用于CI/CD（GCP_SA_KEY），将Cloud Run环境变量用于运行时配置。
如果曾经提交过JSON密钥，请在GCP IAM中撤销和轮换它，从存储库历史记录（BFG/git filter repo）中清除它，并在需要时强制推送清理后的历史记录。

9）故障排除

GET到/mcp/capcorn显示405
- 对的。MCP web传输需要POST/stream。使用/mcp/caporn/meta作为静态JSON元数据。
添加/删除类后的自动加载问题
- 运行composer转储自动加载-o
上游API连接
- 确保可以从您运行的环境访问CAPCORN_BASE_URL。
集装箱网络/PORT
- Cloud Run注入端口；我们的入口点尊重它。在本地，默认值是8080，除非被覆盖。

10）公约和准则

保持工具小巧且可组合。呈现清晰、人类可读的输出字符串。
验证每个输入。快速失败并返回可操作的错误文本。
使用上下文记录错误（避免机密）以简化操作。
在工具描述和README中记录新的端点或参数，以使人类操作员保持在循环中。

附录：项目结构（关键路径）

服务器： CapCornServer类扩展服务器
工具：
路线注册： routes/ai.php
配置： config/services.php
Docker/运行时： Dockerfile, docker/entrypoint.sh
CI/CD： .github/workflows/deploy-cloudrun.yml
脚本： scripts/run_mcp_tests.sh, scripts/run_cloudrun_checks.sh, scripts/start_mcp_server.sh
报告：报告/

11）从Claude和OpenAI GPT（MCP）连接

此服务器在以下位置公开web传输MCP端点：

MCP服务器（POST）：https://mcp-hotel-server-336151914785.europe-west1.run.app/mcp/capcorn
元数据（GET）：https://mcp-hotel-server-336151914785.europe-west1.run.app/mcp/capcorn/meta

元数据路由列出了服务器名称/版本、说明和注册的工具。您可以通过运行以下命令在本地进行验证：

php artisan serve
# POST http://localhost:8000/mcp/capcorn
# GET  http://localhost:8000/mcp/capcorn/meta

A）通过MCP连接器从Claude（桌面/网络）连接

Claude Desktop通过其内置的MCP连接器支持MCP服务器。

文件：

克劳德MCP连接器：https://docs.claude.com/en/docs/agents-and-tools/mcp-connector

步骤（桌面）：

安装克劳德桌面（macOS/Windows）。
打开设置→ “MCP服务器”（如果您喜欢JSON，请编辑Claude Desktop配置文件）。
添加一个指向您的公共可访问URL的新HTTP MCP服务器：
- 名称：山核桃
- URL（服务器）：https://mcp-hotel-server-336151914785.europe-west1.run.app/mcp/capcorn
- 元数据URL（可选但推荐）：https://mcp-hotel-server-336151914785.europe-west1.run.app/mcp/capcorn/meta
如果系统提示，请保存并重新启动Claude Desktop。Claude将发现并列出公开的工具。现在，您可以要求Claude使用这些工具（例如，“搜索房间可用性…”）。

如果您需要身份验证标头（例如，通过代理进行前置时），请将其添加到连接器UI（或配置JSON）中。连接器在每次请求时发送它们。

Claude中的令牌限制：

输出令牌：在Claude API中，设置每个请求的max_Output_tokens（例如，512–1024）。在桌面中，限制与模型/提示设置相关联；保持工具输出简洁，这样助理就不会超出预算。
输入标记：保持系统/指令简短，工具响应紧凑。大型工具输出直接增加了后续操作中的输入令牌使用量。

推荐默认值

工具输出：每次调用的目标是~1-2k个字符。使用项目列表，避免过多的散文。
对于昂贵的搜索，更喜欢总结顶部结果，并包含“再次使用此工具与X获取更多”提示。

B）从OpenAI GPT连接

OpenAI对MCP的支持正在不断发展。目前有两种常见的集成方式：

选项1--本机MCP连接器（如果GPT工作区中有）

在GPT（ChatGPT）构建器UI中，如果“添加MCP服务器”或“MCP连接器”可用，请添加新的HTTP MCP服务器：
- 名称：山核桃
- 服务器URL:https://mcp-hotel-server-336151914785.europe-west1.run.app/mcp/capcorn
- （可选）元数据URL:https://mcp-hotel-server-336151914785.europe-west1.run.app/mcp/capcorn/meta
GPT将发现工具及其模式，并可以在聊天期间调用它们。

选项2——在OpenAI中使用外部MCP客户端/中继

运行一个小型MCP客户端中继，该中继连接到此HTTP服务器，并向OpenAI（助理/响应API）公开可调用函数。
参考实现：
- MCP检查员（非常适合测试）：https://github.com/modelcontextprotocol/inspector
- MCP JS客户端SDK（用于构建中继）：https://github.com/modelcontextprotocol/typescript-sdk
您的中继将MCP工具映射到OpenAI“工具”/“函数”，并将调用转发到https://YOUR_SERVICE_URL/mcp/capcorn，将工具结果返回到OpenAI对话中。

OpenAI令牌限制

输出标记：每次运行时使用模型的max_tokens（或类似）参数（例如，512-1024用于工具结果和解释）。
输入标记：保持工具响应较小，输出较大，如果您的中继支持，可以考虑流式传输汇总结果。

C）示例：Claude Desktop JSON（高级用户）

某些Claude Desktop版本允许MCP服务器进行JSON配置。下面是一个HTTP服务器的示例草图。您的确切模式可能因版本而异；查阅上述官方文件。

{
  "mcpServers": {
    "capcorn": {
      "transport": {
        "type": "http",
        "url": "https://mcp-hotel-server-336151914785.europe-west1.run.app/mcp/capcorn"
      },
      // Optional: metadata helps tools appear with rich descriptions
      "metadataUrl": "https://mcp-hotel-server-336151914785.europe-west1.run.app/mcp/capcorn/meta",
      // Optional headers if you front with a proxy or require auth
      "headers": {
        // "Authorization": "Bearer YOUR_TOKEN"
      },
      // Optional: network timeouts
      "timeoutMs": 30000
    }
  }
}

备注

如果您连接到本地服务器(http://localhost:8000/mcp/capcorn)，将Claude Desktop和服务器保持在同一台机器上，或确保已配置路由。
对于生产，通过HTTPS提供服务。Cloud Run部署已经公开了一个公共HTTPS URL。

D） MCP与LLM使用的最佳实践

使工具具有单一用途和幂等性。LLM可以在需要时链接步骤。
始终验证工具中的输入；返回可操作的错误（例如，哪个字段和预期的格式）。
保持工具结果简短、结构化和确定性。偏好列表/表格；如果结果被截断，请提供下一步指导。
在工具说明中记录工具参数和单位。你的 CapCornServer类扩展服务器 “说明”字段应包含与工具行为一致的最终用户指南。
使用/meta路由验证远程环境中的工具清单（例如Cloud Run）。
代币预算指南：
- 输出标记（助手）：对于大多数步骤，512-1024是一个很好的默认值。
- 输入令牌（上下文）：将指令保持在~2-3k个令牌以下；尽可能将工具输出保持在1~2k个字符以下。
- 对于大型数据集，在工具层分页，让助手请求更多。

使用说明

CapCorn酒店MCP服务器

1） 架构概述

2） 当前工具

3） 配置

4） 本地运行

5） 测试和验证

6） 添加新的MCP工具

7） 部署（谷歌云运行）

8） 安全说明

9） 故障排除

10） 公约和准则

附录：项目结构（关键路径）

11） 从Claude和OpenAI GPT（MCP）连接

A） 通过MCP连接器从Claude（桌面/网络）连接

B） 从OpenAI GPT连接

C） 示例：Claude Desktop JSON（高级用户）

D） MCP与LLM使用的最佳实践

相关 MCP

AKShare One MCP 股市数据服务

实时网络搜索服务

arXiv 论文检索 MCP 服务器

移动自动化MCP服务器

AI持久记忆服务器

Git仓库管理MCP服务器