快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

详细介绍

CapCorn酒店MCP服务器

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

关键能力：

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

MCP端点：

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

快速参考：

- 类SearchRoomsTool扩展工具 - 类SearchRoomAvailability工具扩展工具 - 类CreateReservationTool扩展工具

服务配置： 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：

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, // validate（\[…\]）验证handle（）中的输入，以保护上游并提供可预测的用户体验。

1. 如果添加新的配置密钥，请将其放置在 [config/services.php](config/services.php) 并通过配置（'services.capcorn…'）或新的根级服务块读取它们。

## 7） 部署（谷歌云运行）

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

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

工作流程：

- [deploy-cloudrun.yml](.github/workflows/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](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类扩展服务器](app/Mcp/CapCornServer/CapCornServer.php:10)
- 工具：
  - [类SearchRoomsTool扩展工具](app/Mcp/CapCornServer/Tools/SearchRoomsTool.php:12)
  - [类SearchRoomAvailability工具扩展工具](app/Mcp/CapCornServer/Tools/SearchRoomAvailabilityTool.php:12)
  - [类CreateReservationTool扩展工具](app/Mcp/CapCornServer/Tools/CreateReservationTool.php:12)
- 路线注册： [routes/ai.php](routes/ai.php)
- 配置： [config/services.php](config/services.php)
- Docker/运行时： , 
- CI/CD： 
- 脚本： [scripts/run_mcp_tests.sh](scripts/run_mcp_tests.sh), [scripts/run_cloudrun_checks.sh](scripts/run_cloudrun_checks.sh), [scripts/start_mcp_server.sh](scripts/start_mcp_server.sh)
- 报告： [报告/](reports/)

## 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

步骤（桌面）：

1. 安装克劳德桌面（macOS/Windows）。
1. 打开设置→ “MCP服务器”（如果您喜欢JSON，请编辑Claude Desktop配置文件）。
1. 添加一个指向您的公共可访问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
1. 如果系统提示，请保存并重新启动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类扩展服务器](app/Mcp/CapCornServer/CapCornServer.php:10) “说明”字段应包含与工具行为一致的最终用户指南。
- 使用/meta路由验证远程环境中的工具清单（例如Cloud Run）。
- 代币预算指南：
  - 输出标记（助手）：对于大多数步骤，512-1024是一个很好的默认值。
  - 输入令牌（上下文）：将指令保持在~2-3k个令牌以下；尽可能将工具输出保持在1~2k个字符以下。
  - 对于大型数据集，在工具层分页，让助手请求更多。

目录标签

ClaudeAPI集成云端部署Blade本地部署酒店预订房间发现MCP服务器Laravel应用

支持客户端

Claude DesktopClaude

接入字段

传输方式（transport，传输协议）

未说明

鉴权方式（authType，认证方式）

token

工具数量（toolCount，工具数）

3

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

未说明token部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

仍需确认：installCommand

来源信息

MCP World

mcpworld.com

/detail/026b6414231386433396137fb37eb085

一个基于Laravel的MCP服务器应用，通过上游CapCorn API提供酒店房间发现和预订功能，具有简单、安全和易扩展的特点。

继续浏览同类 MCP

更多运维云端 MCP（13,854）返回 MCP 目录

上一个 MCP

Touch MCP Server

一个使用Golang实现的MCP Server，用于通过JSON-RPC 2.0协议创建文件。

下一个 MCP

tower (The Zacillac)

Tower是一个统一的MCP服务器，整合了多个域名工具项目，提供域名智能、DNS操作和参考数据访问。

Tourism Technology Looking Com MCP Server Hotels