ks-app-sdk 0.3.1

Keystone 平台 MCP Service SDK（Python）

ks-app-sdk (Python)

Keystone 平台 MCP Service SDK（Python 版）。

安装

pip install ks-app-sdk>=0.3.0

快速上手

from ks_app import App

app = App(
    "my-app",
    keystone_auth=True,           # 启用 JWKS strict-by-default
    version="0.1.0",
    manifest_path="manifest.yaml",
)


@app.tool("greet", "打招呼")
async def greet(name: str = "world"):
    return {"message": f"Hello, {name}!"}


# 可选：挂 /config-ui/ 静态前端
# app.mount_config_ui("./web/dist")

# 可选：扩展健康检查
# app.health_check("db", check_db_connection)

if __name__ == "__main__":
    app.run()

鉴权

启用 keystone_auth=True 后，对 /mcp 前缀的请求会强制 JWKS RS256 JWT 验签。

环境变量：

变量	说明
KEYSTONE_JWKS_URL	生产必须设置，指向 Keystone 的 .well-known/jwks.json
KS_APP_AUTH_MODE=insecure	本地开发降级为裸跑（跳过所有鉴权）
KS_APP_PORT / KS_APP_HOST	进程监听配置

strict-by-default：若 keystone_auth=True 且 KEYSTONE_JWKS_URL 未配置， app.create_app() 会抛 AuthResolveError。生产意外漏配时立即暴露，不会静默裸跑。

在工具 handler 中读取 JWT claims：

from ks_app import get_claims


@app.tool("whoami", "查当前用户")
async def whoami():
    claims = get_claims()
    return {"sub": claims.get("sub") if claims else None}

端点

路径	方法	说明
/healthz	GET	存活探针（聚合自定义 health_check）
/readyz	GET	就绪探针
/meta	GET	应用元信息（对齐 ks-types.MetaResponse）
/mcp	POST	MCP Streamable HTTP，JSON-RPC 2.0
/mcp/tools/list	GET	工具列表（legacy）
/mcp/tools/call	POST	调用工具（legacy）
/config-ui/*	GET	前端静态资源（调用 mount_config_ui 后挂载）

配置

环境变量	默认值	说明
KS_APP_PORT	8080	监听端口
KS_APP_HOST	0.0.0.0	监听地址
KEYSTONE_JWKS_URL	—	JWKS 端点；keystone_auth=True 必配
KS_APP_AUTH_MODE	—	insecure 时强制跳过鉴权

依赖

• uvicorn>=0.30
• starlette>=0.37
• pyyaml>=6.0
• PyJWT[crypto]>=2.8.0