Port MCP 服务器

一个用于 Port.io API 的模型上下文协议 (MCP) 服务器，使 Claude 能够与 Port.io 的开发者平台功能进行交互。

安装

获取您的 Port 凭据

1. 创建一个 Port.io 账户：

   • 访问 Port.io
   • 如果您没有账户，请注册一个

2. 创建一个 API 密钥：

   • 导航到您的 Port.io 仪表板
   • 转到设置 > 凭据
   • 保存客户端 ID 和客户端密钥

Claude Desktop

将以下内容添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "port": {
      "command": "uvx",
      "args": [
        "mcp-server-port@0.1.4",
        "--client-id", "YOUR_CLIENT_ID",
        "--client-secret", "YOUR_CLIENT_SECRET",
        "--region", "REGION" # US or EU
      ]
    }
  }
}

Cursor

1. 确保已安装 uvx：

pip install uvx

2. 获取其位置：

which uvx
# 示例输出：/Users/janedoe/.local/bin/uvx

3. 创建一个脚本来运行服务器：

# run-port-mcp.sh

cd /Users/janedoe/.local/bin/uvx

# 使用指定的凭据运行服务器
./.venv/bin/uvx mcp-server-port@0.1.4 --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET --region YOUR_REGION

4. 使其可执行：

chmod +x /path/to/your/file/run-port-mcp.sh

5. 在 Cursor 设置中配置：
   • 转到 Cursor 设置 > MCP 服务器
   • 配置：
     • 名称 - Port
     • 类型 - Command
     • 命令 - /path/to/your/file/run-port-mcp.sh

功能

代理工具

1. trigger_port_agent
   • 使用提示触发 Port.io AI 代理并等待完成
   • 必需输入：
     • prompt (字符串)：发送到 Port.io AI 代理的提示
   • 返回：包含状态、输出和任何所需操作的代理响应
   • 注意：代理可能会返回用于错误报告或其他需要用户交互的任务的操作 URL

蓝图工具

1. get_blueprints

   • 从 Port 检索所有蓝图的列表
   • 可选输入：
     • detailed (布尔值，默认值：false)：返回每个蓝图的完整模式详细信息
   • 返回：所有可用蓝图的格式化文本表示

2. get_blueprint

   • 按标识符检索有关特定蓝图的信息
   • 必需输入：
     • blueprint_identifier (字符串)：要检索的蓝图的唯一标识符
   • 可选输入：
     • detailed (布尔值，默认值：true)：返回完整的模式详细信息
   • 返回：指定蓝图的格式化文本表示

实体工具

将在未来添加。

开发

本地设置

1. 创建并激活虚拟环境：

# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Unix/macOS 上
# 或
.venv\Scripts\activate  # 在 Windows 上

2. 安装依赖项：

# 以开发模式安装
pip install -e .

# 安装开发依赖项
pip install -r requirements-dev.txt

3. 在本地运行服务器：

python -m src.mcp_server_port --client-id "CLIENT_ID" --client-secret "CLIENT_SECRET" --region "REGION"

发布新版本

有两种发布新版本的方法：手动执行所有步骤，或使用自动化的 Make 命令。

手动流程

1. 确保您在 main 分支上并且是最新的：

git checkout main
git pull origin main

2. 将 feature/release 分支与变更日志更新合并：

git merge feature/your-release-branch

3. 更新 pyproject.toml 中的版本

4. 提交版本更新：

git add pyproject.toml
git commit -m "chore: bump version to X.Y.Z"
git push origin main

5. 创建并推送新的 Git 标签：

git tag -a vX.Y.Z -m "Release version X.Y.Z"
git push origin vX.Y.Z

6. 构建并发布到 PyPI：

# 确保您拥有最新的构建工具
pip install --upgrade build twine

# 构建包
python -m build

# 检查包
twine check dist/*

# 上传到 PyPI
twine upload dist/mcp_server_port-X.Y.Z*

7. 创建 GitHub 发布：
   • 转到存储库的 Releases 页面
   • 单击“创建新发布”
   • 选择您刚刚推送的标签
   • 将其标题命名为“Release X.Y.Z”
   • 在描述中包含变更日志
   • 发布该版本

自动化流程

您可以使用提供的 Makefile 命令来自动化发布过程：

# 更新版本并创建发布
make release VERSION=X.Y.Z

# 或单独运行步骤：
make bump-version VERSION=X.Y.Z  # 更新 pyproject.toml
make tag VERSION=X.Y.Z          # 创建并推送 git 标签
make build                      # 构建包
make publish                    # 发布到 PyPI

注意：自动化过程仍然需要您手动创建包含变更日志信息的 GitHub 发布。

故障排除

如果您遇到身份验证错误，请验证：

1. 您的 Port 凭据在参数中设置正确
2. 您拥有必要的权限
3. 凭据已正确复制到您的配置

许可证

此 MCP 服务器已获得 MIT 许可证的许可。 这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。 有关更多详细信息，请参阅项目存储库中的 LICENSE 文件。