北MCP Python SDK
此SDK基于原始SDK构建。请参考 原始存储库的README 获取一般信息。本自述文件侧重于北方的具体细节。
安装
uv pip install git+ssh://git@github.com/cohere-ai/north-mcp-python-sdk.git为什么选择此存储库
此存储库提供代码，使您的服务器能够使用North的身份验证，North是原始规范的自定义扩展。除此之外，SDK没有任何更改；这是建立在它之上的。
主要区别
- North仅支持StreamableHTTP传输。sse传输已弃用，它可以向后兼容，但如果您正在创建新服务器，则不应使用它
- 您可以使用秘密保护对服务器的所有请求。
- 您可以访问用户的OAuth令牌，代表他们与第三方服务进行交互。
- 您可以访问用户的身份（从与North一起使用的身份提供程序）。
- 调试模式 用于详细的身份验证日志记录和故障排除。
例子
此存储库包含可以用作快速入门的示例服务器。你可以在 示例目录.
有两个示例，一个使用auth让用户进行工具调用，另一个显示如何发送正确的元数据，以便North UI可以正确显示工具调用结果。
认证
此SDK提供了几种对用户进行身份验证和授权其请求的策略。
我只希望north能够向我的服务器发送请求
mcp = NorthMCPServer(name="Demo", port=5222, server_secret="secret")我想获取呼叫我服务器的北方用户的身份
参见 examples/server_with_auth.py。在您的请求期间，请致电以下电话：
user = get_authenticated_user()
print(user.email)我需要通过oauth访问第三方服务（例如：谷歌驱动器、slack等）
与上述类似：
user = get_authenticated_user()
print(user.connector_access_tokens)调试模式
North MCP SDK包括一个全面的调试模式，提供身份验证过程、传入请求和令牌验证的详细日志记录。在解决身份验证问题时，这是非常宝贵的。
启用调试模式
有几种方法可以启用调试模式：
1.环境变量（推荐）
export DEBUG=true
python your_server.py2.构造参数
mcp = NorthMCPServer(name="Demo", port=5222, debug=True)在调试模式下记录的内容
启用调试模式后，您将看到详细的日志，包括：
- 请求头：所有传入的HTTP标头（包括授权）
- 令牌解析：身份验证令牌的Base64解码和JSON解析
- JWT验证：用户ID令牌解码和验证步骤
- 身份验证详细信息：用户电子邮件、可用连接器、令牌计数
- 错误上下文：带有故障排除上下文的详细错误消息
调试输出示例
2024-01-15 10:30:45 - NorthMCP.Auth - DEBUG - Authenticating request from ('127.0.0.1', 54321)
2024-01-15 10:30:45 - NorthMCP.Auth - DEBUG - Request headers: {'authorization': 'Bearer eyJ...', 'content-type': 'application/json'}
2024-01-15 10:30:45 - NorthMCP.Auth - DEBUG - Authorization header present (length: 248)
2024-01-15 10:30:45 - NorthMCP.Auth - DEBUG - Successfully decoded base64 auth header
2024-01-15 10:30:45 - NorthMCP.Auth - DEBUG - Successfully parsed auth tokens. Has server_secret: True, Has user_id_token: True, Connector count: 2
2024-01-15 10:30:45 - NorthMCP.Auth - DEBUG - Available connectors: ['google', 'slack']
2024-01-15 10:30:45 - NorthMCP.Auth - DEBUG - Successfully decoded user ID token. Email: user@example.com
2024-01-15 10:30:45 - NorthMCP.AuthContext - DEBUG - Setting authenticated user in context: email=user@example.com, connectors=['google', 'slack']调试模式示例
请参阅- examples/server_with_debug.py 以调试模式为例：
安全说明
调试模式记录敏感信息，包括请求标头和令牌元数据。 切勿在生产环境中启用调试模式 因为它可能会在日志中暴露身份验证细节。
没有北方的地方发展
本指南描述了如何在不将MCP服务器连接到North的情况下在本地测试它。为此，我们将使用MCP检查器。您可以使用以下命令运行它：
npx @modelcontextprotocol/inspector如果不需要身份验证，而您只想在本地运行它，则可以选择stdio传输。导航到 MCP检查员 并按如下方式配置：
- 传输类型：stdio
- 命令：uv
- 参数：运行examples/server_with_auth.py--传输stdio
从这里：
- 点击“连接”
- 选择屏幕顶部的“工具”。
- 点击“列出工具”->“添加”
- 添加数字并单击“运行”。你应该看看总数。
添加身份验证
如果要在本地测试身份验证机制，可以执行以下操作。首先使用可流式传输的http启动服务器：
uv run examples/server_with_auth.py --transport streamable-http接下来，创建一个承载令牌。您可以使用以下命令生成一个 examples/create_bearer_token.py 或者使用预先制作的。
导航到MCP检查器并按如下方式配置：
- 传输类型：流式HTTP
- 网址：http://localhost:5222/mcp
- 身份验证->承载令牌：eyJzZXJ2ZXJfc2VjcmV0IjogInNlcnZlcl9zZWNyZXQiLCAidXNlcl9pZF90b2tlbiI6ICJle UpoYkdjaU9pSklVekxTmlJc0luUjVjQ0k2SWtwWFZDSjkuZXlKbGJXRnBiQ0k2SW5SbGMzUkFZMjl0Y0dGdWVTNWPiMjBpZlEuV0pjckVUUi1mZnFtX2xrdE9vdjd0Q1ktmZYR2JuYTVUMjhaefTaEZ4SSI sICJjb25uZWN0b3JfYWNjZXNzX3Rva2VucyI6IH siZ29vZ2xlIjogImFiYJ9fQ==
按照之前的流程进行。当您调用该工具时，您应该在启动服务器的终端中看到以下日志：
This tool was called by: test@company.com发展
先决条件
要为这个项目做出贡献，你需要：
- Python 3.11+：SDK需要
- 紫外线>=0.8.13：用于依赖关系管理、格式设置和CI检查
设置
- 克隆存储库：
git clone https://github.com/cohere-ai/north-mcp-python-sdk.git
cd north-mcp-python-sdk- 安装依赖项：
uv sync --dev代码格式化
此项目使用 uv format 以实现一致的代码格式。CI管道执行这些标准：
# Check formatting (same as CI)
uv format --preview-features format --check
# Apply formatting
uv format --preview-features format运行测试
uv run pytest贡献
在提交PR之前：
- 确保您的代码通过格式检查：
uv format --preview-features format --check - 运行测试套件：
uv run pytest - 遵循现有的代码样式和模式