axi-cli 0.0.7__tar.gz → 0.0.9__tar.gz

{axi_cli-0.0.7 → axi_cli-0.0.9}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.0.9] - 2026-07-07
+
+### Fixed
+- daemon Unix socket 的 StreamReader 读缓冲从默认 64KB 调大至 8MB：工具数量多时 `axi list` / `axi search` 响应超过单行缓冲上限触发 `LimitOverrunError`，现可正常返回
+
+## [0.0.8] - 2026-07-07
+
+### Added
+- `axi.env(name, default=None)`：native 工具的统一变量读取入口。CLI / stdio 形态下读进程环境变量；经 `axi mcp --transport http` 导出为共享 HTTP server 时，每个客户端通过 `Axi-*` 请求头传入的变量按请求隔离、优先于进程环境变量（`Axi-Foo-Bar` → `FOO_BAR`：去前缀、`-`→`_`、转大写）
+- `mcpServers` 新增 `headers` 字段：连接需认证的 HTTP MCP server 时随每个请求附带（如 `Authorization: Bearer xxx`）；stdio 型凭据继续走 `env`，两种 transport 各用各的通道
+
+### Fixed
+- MCP 连接建立中途失败（如 `initialize` 报错、远端拒绝认证）不再泄漏已打开的资源（httpx 客户端 / 流 / session）：改用 `AsyncExitStack.pop_all()` 惯用法，全部成功才移交所有权，失败由 with 自动清理
+
 ## [0.0.7] - 2026-07-04
 
 ### Added

{axi_cli-0.0.7 → axi_cli-0.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axi-cli
-Version: 0.0.7
+Version: 0.0.9
 Summary: Agent eXecution Interface - unified tool layer for AI Agents
 Requires-Python: >=3.12
 Requires-Dist: bm25s>=0.3.3

{axi_cli-0.0.7 → axi_cli-0.0.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "axi-cli"
-version = "0.0.7"
+version = "0.0.9"
 description = "Agent eXecution Interface - unified tool layer for AI Agents"
 readme = "README.md"
 requires-python = ">=3.12"

{axi_cli-0.0.7 → axi_cli-0.0.9}/skills/axi-creator/SKILL.md

@@ -64,6 +64,21 @@ def get_can_data(
 - 复杂输入用 `BaseModel` 嵌套；axi 会把它展开成 object schema
 - **填 `output_example`**：MCP 协议没有 output schema，原生工具是 axi 独有的优势——Agent 能在 `axi describe` 里直接看到返回形状，不用试跑一遍
 
+### 凭据与配置变量：用 `axi.env`，别用 `os.environ`
+
+工具里需要 API Key 等变量时，一律通过 `axi.env(name, default=None)` 读取：
+
+```python
+import axi
+
+@tool(description="调用上游 API")
+def call_api(query: str) -> dict:
+    key = axi.env("API_KEY")   # CLI/stdio 下读环境变量；HTTP 导出时读客户端 Axi-* header
+    ...
+```
+
+CLI 和 stdio 形态下它就是环境变量；但当工具经 `axi mcp --transport http` 导出为共享 HTTP server 时，每个客户端可通过 `Axi-*` 请求头传自己的变量（见下文"导出为 MCP server"），`axi.env` 会优先取当前请求的值。直接 `os.environ` 的工具在 HTTP 形态下拿不到客户端变量。
+
 ### 注册：两种方式，二选一
 
 **方式 1：本项目内用 → `axi.json` 的 `nativeTools`**
@@ -104,13 +119,14 @@ smartlink = "smartlink_axi.tools"
       "env": {"API_KEY": "xxx"}
     },
     "remote": {
-      "url": "http://localhost:8000/mcp"            // 或 HTTP streaming
+      "url": "http://localhost:8000/mcp",           // 或 HTTP streaming
+      "headers": {"Authorization": "Bearer xxx"}    // 可选：远端要求认证时随每个请求附带
     }
   }
 }
 ```
 
-`command` / `url` 二选一。保存后直接 `axi list` 就能看到新工具——daemon 会按需自动拉起连接。
+`command` / `url` 二选一；凭据传递按 transport 选字段——stdio 用 `env`（注入子进程环境），HTTP 用 `headers`（附到每个请求）。保存后直接 `axi list` 就能看到新工具——daemon 会按需自动拉起连接。
 
 ---
 
@@ -155,6 +171,23 @@ axi mcp --server a,b --transport http --port 8321    # HTTP 长驻服务
 }
 ```
 
+### HTTP 形态下给每个客户端传变量：`Axi-*` header
+
+stdio 是一客户端一进程，变量走 `env` 即可；HTTP 是共享进程，进程环境变量在启动时定死，**每个客户端的变量改走请求头**。约定：`Axi-<名字>` 映射为变量名（去前缀、`-`→`_`、转大写），工具内用 `axi.env` 读取，请求级值优先于进程环境变量：
+
+```json
+{
+  "mcpServers": {
+    "my-tools": {
+      "url": "http://your-host:8321/mcp",
+      "headers": { "Axi-API-KEY": "sk_xxx", "Axi-REGION": "cn" }
+    }
+  }
+}
+```
+
+工具里 `axi.env("API_KEY")` 即得 `sk_xxx`，不同客户端互不可见。注意：这解决的是"客户端带变量进来"，不是服务端准入控制——公网暴露时另需网关层鉴权。
+
 ---
 
 ## 反模式
@@ -163,7 +196,7 @@ axi mcp --server a,b --transport http --port 8321    # HTTP 长驻服务
 - 所有参数都写 `str` — 失去类型约束和枚举提示，Agent 要靠 describe 里的自然语言猜
 - `description` 只写一个词（"搜索"、"查询"）— BM25 召回差、Embedding 语义稀薄
 - 返回不稳定结构（同一工具有时返 list 有时返 dict）— 下游 Agent 没法写聚合逻辑
-- 把敏感配置（API Key）硬编码在 `@tool` 函数里 — 走环境变量或 `mcpServers[...].env`
+- 把敏感配置（API Key）硬编码在 `@tool` 函数里 — 用 `axi.env` 读取（MCP server 的凭据走 `mcpServers[...].env` / `headers`）
 - entry_points 的 value 写成文件路径 `"pkg/tools.py"` — 必须是可 import 的模块路径 `"pkg.tools"`
 
 ---

{axi_cli-0.0.7 → axi_cli-0.0.9}/src/axi/__init__.py

@@ -4,9 +4,10 @@ import logging
 from typing import Any, Callable
 
 from axi.cli import get_executor, get_registry
+from axi.context import env
 from axi.providers.native import register_tool
 
-__all__ = ["tool"]
+__all__ = ["tool", "env"]
 
 # 包级 logger：各子模块通过 logging.getLogger(__name__) 自动继承
 _logger = logging.getLogger("axi")

{axi_cli-0.0.7 → axi_cli-0.0.9}/src/axi/config.py

@@ -109,6 +109,7 @@ class MCPServerConfig(BaseModel):
     args: list[str] = Field(default_factory=list)
     env: dict[str, str] | None = None
     url: str | None = None
+    headers: dict[str, str] | None = None
 
 
 class NativeToolEntry(BaseModel):

axi_cli-0.0.9/src/axi/context.py

@@ -0,0 +1,36 @@
+"""请求级变量：native 工具的统一变量读取入口。
+
+stdio / CLI 形态下变量来自进程环境变量；HTTP MCP 形态下 server 是共享进程，
+每个客户端的变量通过 ``Axi-*`` header 随请求传入，按请求隔离。
+"""
+
+import os
+from collections.abc import Mapping
+from contextvars import ContextVar
+
+_request_env: ContextVar[dict[str, str]] = ContextVar("axi_request_env", default={})
+
+_ENV_HEADER_PREFIX = "axi-"
+
+
+def set_request_env(headers: Mapping[str, str] | None) -> None:
+    """从 ``Axi-*`` header 提取当前请求的变量：``Axi-Foo-Bar`` → ``FOO_BAR``。
+
+    由 mcp_serve 在每次 native 工具调用前调用；``None``（stdio 无请求）置空。
+    ASGI 规范保证 header 名已小写。
+    """
+    _request_env.set(
+        {
+            name.removeprefix(_ENV_HEADER_PREFIX).replace("-", "_").upper(): value
+            for name, value in headers.items()
+            if name.startswith(_ENV_HEADER_PREFIX)
+        }
+        if headers
+        else {}
+    )
+
+
+def env(name: str, default: str | None = None) -> str | None:
+    """读取变量：请求级（HTTP header）优先，其次进程环境变量。"""
+    value = _request_env.get().get(name)
+    return value if value is not None else os.environ.get(name, default)

{axi_cli-0.0.7 → axi_cli-0.0.9}/src/axi/daemon/client.py

@@ -24,6 +24,10 @@ logger = logging.getLogger(__name__)
 _DAEMON_START_POLL_RETRIES = 30
 _DAEMON_START_POLL_INTERVAL = 0.1  # seconds
 
+# StreamReader 缓冲区上限。默认 64KB 放不下完整工具列表（list/search 的响应是单行
+# JSON，工具多时轻松超过 64KB），会抛 asyncio.LimitOverrunError。调大到 8MB。
+_STREAM_LIMIT = 8 * 1024 * 1024
+
 
 def is_daemon_running() -> bool:
     """检查 daemon 是否在运行。"""
@@ -92,7 +96,9 @@ def daemon_request(req: DaemonRequest) -> DaemonResponse:
 
 async def _send(req: DaemonRequest) -> DaemonResponse:
     try:
-        reader, writer = await asyncio.open_unix_connection(SOCKET_PATH)
+        reader, writer = await asyncio.open_unix_connection(
+            SOCKET_PATH, limit=_STREAM_LIMIT
+        )
     except OSError as e:
         return DaemonResponse.fail(
             f"Cannot connect to daemon: {e}. Try: axi daemon stop && axi daemon start"

{axi_cli-0.0.7 → axi_cli-0.0.9}/src/axi/mcp_serve.py

@@ -18,6 +18,7 @@ import mcp.types as types
 from mcp.server.lowlevel import Server
 
 from axi.config import app_config
+from axi.context import set_request_env
 from axi.daemon.client import daemon_request
 from axi.daemon.protocol import LOG_PATH, DaemonRequest
 from axi.executor import Executor
@@ -87,10 +88,18 @@ def build_registry(
 
 
 async def _execute(
-    registry: Registry, executor: Executor, name: str, params: dict[str, Any]
+    server: Server,
+    registry: Registry,
+    executor: Executor,
+    name: str,
+    params: dict[str, Any],
 ) -> RunResult:
     """按来源分发执行：native 进程内，MCP 转发 daemon。
 
+    native 执行前把当前 HTTP 请求的 Axi-* header 写入请求级变量
+    （stdio 无请求对象，置空）；MCP 工具在 daemon 进程执行，读不到
+    contextvar，不捕获。
+
     Executor.run 与 send_request 内部都会 asyncio.run，
     必须放到 worker 线程执行以避免嵌套事件循环。
     """
@@ -100,6 +109,8 @@ async def _execute(
         return RunResult.fail(str(e))
 
     if meta.source == ToolSource.NATIVE:
+        request = server.request_context.request
+        set_request_env(request.headers if request else None)
         return await asyncio.to_thread(executor.run, meta.full_name, params)
 
     # daemon_request 内含 ensure_daemon：daemon idle 自杀后长驻 serve 进程可自动重启它
@@ -174,7 +185,7 @@ def _build_flat_server(registry: Registry, executor: Executor) -> Server:
             raise ValueError(
                 f"Unknown tool: {name}. Call tools/list to see the available tools."
             )
-        result = await _execute(registry, executor, full_name, arguments)
+        result = await _execute(server, registry, executor, full_name, arguments)
         if result.status == "error":
             raise RuntimeError(result.error)
         return _text(result.data)
@@ -269,7 +280,11 @@ def _build_meta_server(registry: Registry, executor: Executor) -> Server:
             return _text(out[0] if len(out) == 1 else out)
         if name == "run":
             result = await _execute(
-                registry, executor, arguments["name"], arguments.get("params") or {}
+                server,
+                registry,
+                executor,
+                arguments["name"],
+                arguments.get("params") or {},
             )
             return _text(result.model_dump(exclude_none=True))
         raise ValueError(

{axi_cli-0.0.7 → axi_cli-0.0.9}/src/axi/providers/mcp.py

@@ -8,6 +8,7 @@ import threading
 from contextlib import AsyncExitStack
 from typing import Any, Self
 
+import httpx
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.stdio import stdio_client
 from mcp.client.streamable_http import streamable_http_client
@@ -49,27 +50,40 @@ class MCPConnection:
         self._exit_stack: AsyncExitStack | None = None
 
     async def connect(self) -> None:
-        """建立连接并初始化 session。"""
-        self._exit_stack = AsyncExitStack()
-
-        if self.config.url:
-            read_stream, write_stream, _ = await self._exit_stack.enter_async_context(
-                streamable_http_client(self.config.url)
-            )
-        else:
-            server_params = StdioServerParameters(
-                command=self.config.command,
-                args=self.config.args,
-                env=self.config.env,
-            )
-            devnull = self._exit_stack.enter_context(open(os.devnull, "w"))
-            read_stream, write_stream = await self._exit_stack.enter_async_context(
-                stdio_client(server_params, errlog=devnull)
+        """建立连接并初始化 session。中途失败时 with 退出自动清理已打开的资源。"""
+        async with AsyncExitStack() as stack:
+            if self.config.url:
+                http_client = None
+                if self.config.headers:
+                    # 超时与 SDK 默认客户端（create_mcp_http_client）一致：
+                    # 读超时 300s 是 SSE 长调用的存活窗口，不能用整体 30s
+                    http_client = await stack.enter_async_context(
+                        httpx.AsyncClient(
+                            headers=self.config.headers,
+                            timeout=httpx.Timeout(30, read=300),
+                            follow_redirects=True,
+                        )
+                    )
+                read_stream, write_stream, _ = await stack.enter_async_context(
+                    streamable_http_client(self.config.url, http_client=http_client)
+                )
+            else:
+                server_params = StdioServerParameters(
+                    command=self.config.command,
+                    args=self.config.args,
+                    env=self.config.env,
+                )
+                devnull = stack.enter_context(open(os.devnull, "w"))
+                read_stream, write_stream = await stack.enter_async_context(
+                    stdio_client(server_params, errlog=devnull)
+                )
+            session = await stack.enter_async_context(
+                ClientSession(read_stream, write_stream)
             )
-        self.session = await self._exit_stack.enter_async_context(
-            ClientSession(read_stream, write_stream)
-        )
-        await self.session.initialize()
+            await session.initialize()
+            # 全部成功才接管资源所有权；此前任何一步抛出都由 with 清理
+            self._exit_stack = stack.pop_all()
+            self.session = session
 
     async def list_tools(self) -> list[ToolMeta]:
         """获取该 server 的所有工具。"""