cortexhub 2.0.5__tar.gz → 2.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cortexhub-2.1.0/.gitignore +11 -0
- {cortexhub-2.0.5 → cortexhub-2.1.0}/PKG-INFO +10 -11
- {cortexhub-2.0.5 → cortexhub-2.1.0}/README.md +9 -10
- {cortexhub-2.0.5 → cortexhub-2.1.0}/pyproject.toml +4 -4
- {cortexhub-2.0.5 → cortexhub-2.1.0}/src/cortexhub/__init__.py +8 -8
- {cortexhub-2.0.5 → cortexhub-2.1.0}/src/cortexhub/client.py +8 -18
- {cortexhub-2.0.5 → cortexhub-2.1.0}/src/cortexhub/mcp_key.py +8 -58
- {cortexhub-2.0.5 → cortexhub-2.1.0}/src/cortexhub/mcp_oauth.py +3 -40
- cortexhub-2.0.5/.gitignore +0 -104
- {cortexhub-2.0.5 → cortexhub-2.1.0}/LICENSE +0 -0
- {cortexhub-2.0.5 → cortexhub-2.1.0}/src/cortexhub/_config.py +0 -0
- {cortexhub-2.0.5 → cortexhub-2.1.0}/src/cortexhub/errors.py +0 -0
- {cortexhub-2.0.5 → cortexhub-2.1.0}/src/cortexhub/session.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: cortexhub
|
|
3
|
-
Version: 2.0
|
|
3
|
+
Version: 2.1.0
|
|
4
4
|
Summary: MCP gateway client for CortexHub programmatic agent access.
|
|
5
5
|
Project-URL: Homepage, https://cortexhub.ai
|
|
6
6
|
Project-URL: Documentation, https://docs.cortexhub.ai
|
|
@@ -26,7 +26,7 @@ Official Python client for the **CortexHub MCP gateway**.
|
|
|
26
26
|
|
|
27
27
|
This package builds the URL and headers your MCP transport needs to call
|
|
28
28
|
`https://mcp.cortexhub.ai/v1/mcp`. It does not call the CortexHub
|
|
29
|
-
Platform API; for organisation and
|
|
29
|
+
Platform API; for organisation, agent, and member management, see the
|
|
30
30
|
[Platform API reference](https://docs.cortexhub.ai/docs/rest-api/overview).
|
|
31
31
|
|
|
32
32
|
[Documentation](https://docs.cortexhub.ai/docs/sdks/overview)
|
|
@@ -42,13 +42,13 @@ pip install cortexhub
|
|
|
42
42
|
The SDK supports both gateway authentication paths through one entry
|
|
43
43
|
point. Pick the one that matches how your application identifies users.
|
|
44
44
|
|
|
45
|
-
###
|
|
45
|
+
### Org MCP API key (recommended for backends)
|
|
46
46
|
|
|
47
47
|
Use this when your application has its own users who do not have
|
|
48
|
-
CortexHub accounts. The
|
|
48
|
+
CortexHub accounts. The org key authenticates the gateway; the
|
|
49
49
|
end-user identity is attested per call.
|
|
50
50
|
|
|
51
|
-
Mint the key from **
|
|
51
|
+
Mint the key from **Settings -> MCP API keys** in the
|
|
52
52
|
CortexHub dashboard, or programmatically via the Platform API.
|
|
53
53
|
|
|
54
54
|
```python
|
|
@@ -59,15 +59,14 @@ session = cx.session(
|
|
|
59
59
|
agent="invoice-bot",
|
|
60
60
|
end_user_subject="user_42", # required for end-user accountability policies
|
|
61
61
|
end_user_display_hint="Alice", # optional, render-only, never persisted
|
|
62
|
-
invocation_mode="autonomous", # default; pass "interactive" if a human is present
|
|
63
62
|
)
|
|
64
|
-
# session.mcp.url and session.mcp.headers
|
|
63
|
+
# session.mcp.url and session.mcp.headers -> pass to your MCP transport
|
|
65
64
|
```
|
|
66
65
|
|
|
67
66
|
### MCP OAuth client
|
|
68
67
|
|
|
69
68
|
Use this when your application signs in CortexHub users interactively.
|
|
70
|
-
Create the OAuth client from **Account settings
|
|
69
|
+
Create the OAuth client from **Account settings -> MCP OAuth clients** and
|
|
71
70
|
copy the `client_id` and `client_secret`.
|
|
72
71
|
|
|
73
72
|
```python
|
|
@@ -87,9 +86,9 @@ session = cx.session(
|
|
|
87
86
|
| Variable | Default | Purpose |
|
|
88
87
|
|---|---|---|
|
|
89
88
|
| `CORTEXHUB_URL` | `https://mcp.cortexhub.ai` | MCP gateway base URL |
|
|
90
|
-
| `CORTEXHUB_API_KEY` |
|
|
91
|
-
| `CORTEXHUB_CLIENT_ID` |
|
|
92
|
-
| `CORTEXHUB_CLIENT_SECRET` |
|
|
89
|
+
| `CORTEXHUB_API_KEY` | - | Org MCP API key (`cxh_mcpk_*`) |
|
|
90
|
+
| `CORTEXHUB_CLIENT_ID` | - | MCP OAuth client id |
|
|
91
|
+
| `CORTEXHUB_CLIENT_SECRET` | - | MCP OAuth client secret |
|
|
93
92
|
|
|
94
93
|
If both `CORTEXHUB_API_KEY` and OAuth credentials are configured, the
|
|
95
94
|
API key wins.
|
|
@@ -4,7 +4,7 @@ Official Python client for the **CortexHub MCP gateway**.
|
|
|
4
4
|
|
|
5
5
|
This package builds the URL and headers your MCP transport needs to call
|
|
6
6
|
`https://mcp.cortexhub.ai/v1/mcp`. It does not call the CortexHub
|
|
7
|
-
Platform API; for organisation and
|
|
7
|
+
Platform API; for organisation, agent, and member management, see the
|
|
8
8
|
[Platform API reference](https://docs.cortexhub.ai/docs/rest-api/overview).
|
|
9
9
|
|
|
10
10
|
[Documentation](https://docs.cortexhub.ai/docs/sdks/overview)
|
|
@@ -20,13 +20,13 @@ pip install cortexhub
|
|
|
20
20
|
The SDK supports both gateway authentication paths through one entry
|
|
21
21
|
point. Pick the one that matches how your application identifies users.
|
|
22
22
|
|
|
23
|
-
###
|
|
23
|
+
### Org MCP API key (recommended for backends)
|
|
24
24
|
|
|
25
25
|
Use this when your application has its own users who do not have
|
|
26
|
-
CortexHub accounts. The
|
|
26
|
+
CortexHub accounts. The org key authenticates the gateway; the
|
|
27
27
|
end-user identity is attested per call.
|
|
28
28
|
|
|
29
|
-
Mint the key from **
|
|
29
|
+
Mint the key from **Settings -> MCP API keys** in the
|
|
30
30
|
CortexHub dashboard, or programmatically via the Platform API.
|
|
31
31
|
|
|
32
32
|
```python
|
|
@@ -37,15 +37,14 @@ session = cx.session(
|
|
|
37
37
|
agent="invoice-bot",
|
|
38
38
|
end_user_subject="user_42", # required for end-user accountability policies
|
|
39
39
|
end_user_display_hint="Alice", # optional, render-only, never persisted
|
|
40
|
-
invocation_mode="autonomous", # default; pass "interactive" if a human is present
|
|
41
40
|
)
|
|
42
|
-
# session.mcp.url and session.mcp.headers
|
|
41
|
+
# session.mcp.url and session.mcp.headers -> pass to your MCP transport
|
|
43
42
|
```
|
|
44
43
|
|
|
45
44
|
### MCP OAuth client
|
|
46
45
|
|
|
47
46
|
Use this when your application signs in CortexHub users interactively.
|
|
48
|
-
Create the OAuth client from **Account settings
|
|
47
|
+
Create the OAuth client from **Account settings -> MCP OAuth clients** and
|
|
49
48
|
copy the `client_id` and `client_secret`.
|
|
50
49
|
|
|
51
50
|
```python
|
|
@@ -65,9 +64,9 @@ session = cx.session(
|
|
|
65
64
|
| Variable | Default | Purpose |
|
|
66
65
|
|---|---|---|
|
|
67
66
|
| `CORTEXHUB_URL` | `https://mcp.cortexhub.ai` | MCP gateway base URL |
|
|
68
|
-
| `CORTEXHUB_API_KEY` |
|
|
69
|
-
| `CORTEXHUB_CLIENT_ID` |
|
|
70
|
-
| `CORTEXHUB_CLIENT_SECRET` |
|
|
67
|
+
| `CORTEXHUB_API_KEY` | - | Org MCP API key (`cxh_mcpk_*`) |
|
|
68
|
+
| `CORTEXHUB_CLIENT_ID` | - | MCP OAuth client id |
|
|
69
|
+
| `CORTEXHUB_CLIENT_SECRET` | - | MCP OAuth client secret |
|
|
71
70
|
|
|
72
71
|
If both `CORTEXHUB_API_KEY` and OAuth credentials are configured, the
|
|
73
72
|
API key wins.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "cortexhub"
|
|
3
|
-
version = "2.0
|
|
3
|
+
version = "2.1.0"
|
|
4
4
|
description = "MCP gateway client for CortexHub programmatic agent access."
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
requires-python = ">=3.10"
|
|
@@ -71,7 +71,7 @@ python-preference = "only-managed"
|
|
|
71
71
|
|
|
72
72
|
[dependency-groups]
|
|
73
73
|
dev = [
|
|
74
|
-
"pytest
|
|
75
|
-
"ruff
|
|
76
|
-
"mypy
|
|
74
|
+
"pytest==9.0.3",
|
|
75
|
+
"ruff==0.14.11",
|
|
76
|
+
"mypy==1.19.1",
|
|
77
77
|
]
|
|
@@ -2,14 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
This package builds the URL and headers your MCP transport needs to
|
|
4
4
|
call ``https://mcp.cortexhub.ai/v1/mcp``. It does not call the
|
|
5
|
-
CortexHub Platform API; for organisation and
|
|
6
|
-
the Platform API directly.
|
|
5
|
+
CortexHub Platform API; for organisation, agent, and member management,
|
|
6
|
+
use the Platform API directly.
|
|
7
7
|
|
|
8
8
|
Two gateway authentication paths through one entry point:
|
|
9
9
|
|
|
10
10
|
.. code-block:: python
|
|
11
11
|
|
|
12
|
-
#
|
|
12
|
+
# Org MCP API key (recommended for backends):
|
|
13
13
|
from cortexhub import Cortexhub
|
|
14
14
|
cx = Cortexhub(api_key="cxh_mcpk_<id>_<secret>")
|
|
15
15
|
session = cx.session(agent="invoice-bot", end_user_subject="user_42")
|
|
@@ -30,18 +30,18 @@ from .mcp_key import CortexhubKeyClient, McpKeySession
|
|
|
30
30
|
from .mcp_oauth import CortexhubMcpOAuthClient, McpOAuthSession, McpOAuthToken
|
|
31
31
|
from .session import SessionMcp
|
|
32
32
|
|
|
33
|
-
__version__ = "2.0
|
|
33
|
+
__version__ = "2.1.0"
|
|
34
34
|
__all__ = [
|
|
35
|
+
"APIError",
|
|
36
|
+
"AuthenticationError",
|
|
37
|
+
"ConfigurationError",
|
|
35
38
|
"Cortexhub",
|
|
39
|
+
"CortexhubError",
|
|
36
40
|
"CortexhubKeyClient",
|
|
37
41
|
"CortexhubMcpOAuthClient",
|
|
38
42
|
"McpKeySession",
|
|
39
43
|
"McpOAuthSession",
|
|
40
44
|
"McpOAuthToken",
|
|
41
45
|
"SessionMcp",
|
|
42
|
-
"CortexhubError",
|
|
43
|
-
"ConfigurationError",
|
|
44
|
-
"AuthenticationError",
|
|
45
|
-
"APIError",
|
|
46
46
|
"__version__",
|
|
47
47
|
]
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Two authentication paths are supported through one entry point:
|
|
4
4
|
|
|
5
|
-
* **
|
|
5
|
+
* **Org MCP API key** (recommended for backends whose end users do
|
|
6
6
|
not have CortexHub accounts):
|
|
7
7
|
|
|
8
8
|
.. code-block:: python
|
|
@@ -32,11 +32,11 @@ from .mcp_oauth import CortexhubMcpOAuthClient, McpOAuthSession, McpOAuthToken
|
|
|
32
32
|
|
|
33
33
|
|
|
34
34
|
class Cortexhub:
|
|
35
|
-
"""MCP gateway client. Pass either
|
|
35
|
+
"""MCP gateway client. Pass either an org API key OR OAuth credentials.
|
|
36
36
|
|
|
37
37
|
Environment variables (optional fallbacks):
|
|
38
38
|
|
|
39
|
-
- ``CORTEXHUB_API_KEY`` --
|
|
39
|
+
- ``CORTEXHUB_API_KEY`` -- org MCP API key (``cxh_mcpk_*``)
|
|
40
40
|
- ``CORTEXHUB_CLIENT_ID`` and ``CORTEXHUB_CLIENT_SECRET`` -- MCP OAuth credentials
|
|
41
41
|
- ``CORTEXHUB_URL`` -- gateway base URL (default ``https://mcp.cortexhub.ai``)
|
|
42
42
|
|
|
@@ -79,7 +79,7 @@ class Cortexhub:
|
|
|
79
79
|
return
|
|
80
80
|
|
|
81
81
|
raise ConfigurationError(
|
|
82
|
-
"Missing credentials. Pass api_key= (
|
|
82
|
+
"Missing credentials. Pass api_key= (org MCP API key) OR "
|
|
83
83
|
"client_id= and client_secret= (MCP OAuth client). You can also "
|
|
84
84
|
"set CORTEXHUB_API_KEY, or CORTEXHUB_CLIENT_ID and "
|
|
85
85
|
"CORTEXHUB_CLIENT_SECRET."
|
|
@@ -99,14 +99,13 @@ class Cortexhub:
|
|
|
99
99
|
end_user_display_hint: str | None = None,
|
|
100
100
|
conversation_title: str | None = None,
|
|
101
101
|
last_user_message: str | None = None,
|
|
102
|
-
invocation_mode: Literal["interactive", "autonomous"] | None = None,
|
|
103
102
|
refresh: bool = False,
|
|
104
103
|
) -> McpKeySession | McpOAuthSession:
|
|
105
104
|
"""Return MCP transport details (``.mcp.url`` and ``.mcp.headers``).
|
|
106
105
|
|
|
107
106
|
``agent`` is required on every call.
|
|
108
107
|
|
|
109
|
-
**
|
|
108
|
+
**Org API key mode**: pass ``end_user_subject`` to attest
|
|
110
109
|
the end user the call is acting on behalf of. The gateway
|
|
111
110
|
requires it for any policy with end-user accountability; missing
|
|
112
111
|
it on such a call returns HTTP 400. ``end_user_display_hint`` is
|
|
@@ -118,13 +117,6 @@ class Cortexhub:
|
|
|
118
117
|
attached so operators can see session context when reviewing
|
|
119
118
|
spans for this session in CortexHub.
|
|
120
119
|
|
|
121
|
-
``invocation_mode``:
|
|
122
|
-
|
|
123
|
-
* ``"interactive"`` -- a human is present and can answer
|
|
124
|
-
in-client consent prompts. Default for OAuth callers.
|
|
125
|
-
* ``"autonomous"`` -- cron jobs, queue workers, webhook handlers,
|
|
126
|
-
and other unattended runs. Default for workspace-key callers.
|
|
127
|
-
|
|
128
120
|
``refresh`` only applies to OAuth mode -- force a refresh-token
|
|
129
121
|
exchange instead of reusing the cached token.
|
|
130
122
|
"""
|
|
@@ -135,7 +127,6 @@ class Cortexhub:
|
|
|
135
127
|
mcp_session_id=mcp_session_id,
|
|
136
128
|
end_user_subject=end_user_subject,
|
|
137
129
|
end_user_display_hint=end_user_display_hint,
|
|
138
|
-
invocation_mode=invocation_mode,
|
|
139
130
|
)
|
|
140
131
|
assert self._oauth_backend is not None
|
|
141
132
|
return self._oauth_backend.session(
|
|
@@ -143,7 +134,6 @@ class Cortexhub:
|
|
|
143
134
|
mcp_session_id=mcp_session_id,
|
|
144
135
|
conversation_title=conversation_title,
|
|
145
136
|
last_user_message=last_user_message,
|
|
146
|
-
invocation_mode=invocation_mode,
|
|
147
137
|
refresh=refresh,
|
|
148
138
|
)
|
|
149
139
|
|
|
@@ -165,13 +155,13 @@ class Cortexhub:
|
|
|
165
155
|
def fetch_token(self, *, refresh: bool = False) -> McpOAuthToken:
|
|
166
156
|
"""OAuth-mode only. Mint or refresh an access token directly.
|
|
167
157
|
|
|
168
|
-
Raises ``RuntimeError`` if the client was built with
|
|
158
|
+
Raises ``RuntimeError`` if the client was built with an org
|
|
169
159
|
API key -- those do not require a token exchange.
|
|
170
160
|
"""
|
|
171
161
|
if self._oauth_backend is None:
|
|
172
162
|
raise RuntimeError(
|
|
173
163
|
"fetch_token() is only available when the client was built "
|
|
174
|
-
"with client_id and client_secret.
|
|
164
|
+
"with client_id and client_secret. Org API keys do not "
|
|
175
165
|
"require a token exchange."
|
|
176
166
|
)
|
|
177
167
|
return self._oauth_backend.fetch_token(refresh=refresh)
|
|
@@ -181,5 +171,5 @@ class Cortexhub:
|
|
|
181
171
|
return f"Cortexhub(api_key={self._key_backend.masked_key!r})"
|
|
182
172
|
assert self._oauth_backend is not None
|
|
183
173
|
cid = self._oauth_backend.client_id
|
|
184
|
-
prefix = cid[:12] + "
|
|
174
|
+
prefix = cid[:12] + "..." if len(cid) > 12 else cid
|
|
185
175
|
return f"Cortexhub(client_id={prefix!r})"
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
"""
|
|
1
|
+
"""Org MCP API key client.
|
|
2
2
|
|
|
3
3
|
Use this when your backend acts on behalf of users who do not have
|
|
4
|
-
CortexHub identities. The
|
|
4
|
+
CortexHub identities. The org MCP API key authenticates the
|
|
5
5
|
gateway; the end-user identity is attested per call via
|
|
6
6
|
``X-CortexHub-End-User-Subject``. No CortexHub user row is created
|
|
7
7
|
for the end user, no email is required, no PII is stored.
|
|
@@ -13,7 +13,6 @@ For applications that sign in CortexHub users interactively, see
|
|
|
13
13
|
from __future__ import annotations
|
|
14
14
|
|
|
15
15
|
from dataclasses import dataclass, field
|
|
16
|
-
from typing import Literal
|
|
17
16
|
|
|
18
17
|
from ._config import base_url
|
|
19
18
|
from .session import SessionMcp
|
|
@@ -22,18 +21,13 @@ _KEY_HEADER = "X-CortexHub-Key"
|
|
|
22
21
|
_AGENT_HEADER = "X-CortexHub-Agent"
|
|
23
22
|
_END_USER_SUBJECT_HEADER = "X-CortexHub-End-User-Subject"
|
|
24
23
|
_END_USER_DISPLAY_HINT_HEADER = "X-CortexHub-End-User-Display-Hint"
|
|
25
|
-
_INVOCATION_MODE_HEADER = "X-CortexHub-Invocation-Mode"
|
|
26
|
-
|
|
27
|
-
InvocationMode = Literal["interactive", "autonomous"]
|
|
28
|
-
|
|
29
|
-
_VALID_INVOCATION_MODES = frozenset({"interactive", "autonomous"})
|
|
30
24
|
|
|
31
25
|
_KEY_PREFIX = "cxh_mcpk_"
|
|
32
26
|
|
|
33
27
|
|
|
34
28
|
@dataclass
|
|
35
29
|
class McpKeySession:
|
|
36
|
-
"""MCP connection using
|
|
30
|
+
"""MCP connection using an org API key + per-call end-user attestation.
|
|
37
31
|
|
|
38
32
|
Wire into your MCP transport via ``session.mcp.url`` and
|
|
39
33
|
``session.mcp.headers``.
|
|
@@ -44,7 +38,6 @@ class McpKeySession:
|
|
|
44
38
|
mcp_session_id: str | None = None
|
|
45
39
|
end_user_subject: str | None = None
|
|
46
40
|
end_user_display_hint: str | None = None
|
|
47
|
-
invocation_mode: InvocationMode | None = None
|
|
48
41
|
mcp: SessionMcp = field(init=False)
|
|
49
42
|
|
|
50
43
|
def __post_init__(self) -> None:
|
|
@@ -58,22 +51,11 @@ class McpKeySession:
|
|
|
58
51
|
headers[_END_USER_SUBJECT_HEADER] = self.end_user_subject
|
|
59
52
|
if self.end_user_display_hint:
|
|
60
53
|
headers[_END_USER_DISPLAY_HINT_HEADER] = self.end_user_display_hint
|
|
61
|
-
if self.invocation_mode:
|
|
62
|
-
headers[_INVOCATION_MODE_HEADER] = self.invocation_mode
|
|
63
54
|
self.mcp = SessionMcp(url=f"{base_url()}/v1/mcp", headers=headers)
|
|
64
55
|
|
|
65
56
|
|
|
66
57
|
class CortexhubKeyClient:
|
|
67
|
-
"""Send MCP gateway calls authenticated by
|
|
68
|
-
|
|
69
|
-
The key looks like ``cxh_mcpk_<id>_<secret>`` and is minted in your
|
|
70
|
-
workspace settings (or via the Platform API). It is tenant-scoped: one
|
|
71
|
-
key, one workspace.
|
|
72
|
-
|
|
73
|
-
Unlike OAuth this is **not** a token-exchange flow. The key itself is
|
|
74
|
-
sent on every request as ``X-CortexHub-Key``. There is nothing to
|
|
75
|
-
refresh and no JWT involved.
|
|
76
|
-
"""
|
|
58
|
+
"""Send MCP gateway calls authenticated by an org MCP API key."""
|
|
77
59
|
|
|
78
60
|
def __init__(self, *, api_key: str) -> None:
|
|
79
61
|
cleaned = (api_key or "").strip()
|
|
@@ -81,7 +63,7 @@ class CortexhubKeyClient:
|
|
|
81
63
|
raise ValueError("api_key= is required.")
|
|
82
64
|
if not cleaned.startswith(_KEY_PREFIX):
|
|
83
65
|
raise ValueError(
|
|
84
|
-
f"api_key must start with {_KEY_PREFIX!r}.
|
|
66
|
+
f"api_key must start with {_KEY_PREFIX!r}. Org MCP API "
|
|
85
67
|
"keys begin with this prefix; if you have an OAuth client_id "
|
|
86
68
|
"and client_secret instead, use the OAuth credentials path."
|
|
87
69
|
)
|
|
@@ -90,13 +72,10 @@ class CortexhubKeyClient:
|
|
|
90
72
|
@property
|
|
91
73
|
def masked_key(self) -> str:
|
|
92
74
|
"""Return the key id portion with the secret masked, for logs and repr."""
|
|
93
|
-
# The key splits on the FIRST underscore after the prefix. The id
|
|
94
|
-
# tail is base36 (no underscores); the secret may contain
|
|
95
|
-
# underscores. So we find the first separator AFTER the prefix.
|
|
96
75
|
sep = self.api_key.find("_", len(_KEY_PREFIX))
|
|
97
76
|
if sep <= len(_KEY_PREFIX):
|
|
98
|
-
return self.api_key[:12] + "
|
|
99
|
-
return self.api_key[:sep] + "_
|
|
77
|
+
return self.api_key[:12] + "..."
|
|
78
|
+
return self.api_key[:sep] + "_..."
|
|
100
79
|
|
|
101
80
|
def session(
|
|
102
81
|
self,
|
|
@@ -105,45 +84,16 @@ class CortexhubKeyClient:
|
|
|
105
84
|
mcp_session_id: str | None = None,
|
|
106
85
|
end_user_subject: str | None = None,
|
|
107
86
|
end_user_display_hint: str | None = None,
|
|
108
|
-
invocation_mode: InvocationMode | None = None,
|
|
109
87
|
) -> McpKeySession:
|
|
110
|
-
"""Return MCP transport headers for a single agent call.
|
|
111
|
-
|
|
112
|
-
``agent`` is the workspace agent reference (a human-friendly slug
|
|
113
|
-
or a ``cxh_agent_*`` id). On first sight of a new ref the gateway
|
|
114
|
-
creates the agent inside the workspace; subsequent calls reuse it.
|
|
115
|
-
|
|
116
|
-
``end_user_subject`` is the opaque identifier of the user the call
|
|
117
|
-
is acting on behalf of. The gateway requires it for any policy
|
|
118
|
-
with end-user accountability; missing it on such a call returns
|
|
119
|
-
HTTP 400. The string is yours, the only constraint is that it
|
|
120
|
-
identifies the same end user consistently across calls.
|
|
121
|
-
|
|
122
|
-
``end_user_display_hint`` is an optional short label shown in
|
|
123
|
-
consent dialogs (e.g. ``"Alice"``). It is render-only and is
|
|
124
|
-
**never** persisted on any audit, decision, receipt, or span row.
|
|
125
|
-
|
|
126
|
-
``mcp_session_id`` groups tool activity into a single workspace
|
|
127
|
-
session.
|
|
128
|
-
|
|
129
|
-
``invocation_mode`` defaults to ``"autonomous"`` on the gateway
|
|
130
|
-
for API-key callers; set ``"interactive"`` explicitly if a human
|
|
131
|
-
is present at the time of the call and can answer in-client
|
|
132
|
-
consent prompts.
|
|
133
|
-
"""
|
|
88
|
+
"""Return MCP transport headers for a single agent call."""
|
|
134
89
|
if not agent or not agent.strip():
|
|
135
90
|
raise ValueError("agent= is required.")
|
|
136
|
-
if invocation_mode is not None and invocation_mode not in _VALID_INVOCATION_MODES:
|
|
137
|
-
raise ValueError(
|
|
138
|
-
"invocation_mode must be 'interactive' or 'autonomous'."
|
|
139
|
-
)
|
|
140
91
|
return McpKeySession(
|
|
141
92
|
api_key=self.api_key,
|
|
142
93
|
agent=agent.strip(),
|
|
143
94
|
mcp_session_id=(mcp_session_id or "").strip() or None,
|
|
144
95
|
end_user_subject=(end_user_subject or "").strip() or None,
|
|
145
96
|
end_user_display_hint=(end_user_display_hint or "").strip() or None,
|
|
146
|
-
invocation_mode=invocation_mode,
|
|
147
97
|
)
|
|
148
98
|
|
|
149
99
|
def __repr__(self) -> str:
|
|
@@ -1,10 +1,4 @@
|
|
|
1
|
-
"""MCP OAuth client for users with a CortexHub identity.
|
|
2
|
-
|
|
3
|
-
Use this when your MCP client signs in an interactive CortexHub user (for
|
|
4
|
-
example, your application has a logged-in user that maps to a CortexHub
|
|
5
|
-
member). For programmatic backends that act on behalf of users who do not
|
|
6
|
-
have CortexHub identities, use :mod:`cortexhub.mcp_key` instead.
|
|
7
|
-
"""
|
|
1
|
+
"""MCP OAuth client for users with a CortexHub identity."""
|
|
8
2
|
|
|
9
3
|
from __future__ import annotations
|
|
10
4
|
|
|
@@ -13,13 +7,12 @@ import urllib.error
|
|
|
13
7
|
import urllib.parse
|
|
14
8
|
import urllib.request
|
|
15
9
|
from dataclasses import dataclass, field
|
|
16
|
-
from typing import Any
|
|
10
|
+
from typing import Any
|
|
17
11
|
|
|
18
12
|
from ._config import base_url
|
|
19
13
|
from .errors import APIError, AuthenticationError
|
|
20
14
|
from .session import SessionMcp
|
|
21
15
|
|
|
22
|
-
_INVOCATION_MODE_HEADER = "X-CortexHub-Invocation-Mode"
|
|
23
16
|
_AGENT_HEADER = "X-CortexHub-Agent"
|
|
24
17
|
_CONVERSATION_TITLE_HEADER = "X-CortexHub-Conversation-Title"
|
|
25
18
|
_LAST_USER_MESSAGE_HEADER = "X-CortexHub-Last-User-Message"
|
|
@@ -35,11 +28,6 @@ class McpOAuthToken:
|
|
|
35
28
|
scope: str = ""
|
|
36
29
|
|
|
37
30
|
|
|
38
|
-
InvocationMode = Literal["interactive", "autonomous"]
|
|
39
|
-
|
|
40
|
-
_VALID_INVOCATION_MODES = frozenset({"interactive", "autonomous"})
|
|
41
|
-
|
|
42
|
-
|
|
43
31
|
@dataclass
|
|
44
32
|
class McpOAuthSession:
|
|
45
33
|
"""MCP connection using Bearer JWT + optional agent and session headers."""
|
|
@@ -49,7 +37,6 @@ class McpOAuthSession:
|
|
|
49
37
|
mcp_session_id: str | None = None
|
|
50
38
|
conversation_title: str | None = None
|
|
51
39
|
last_user_message: str | None = None
|
|
52
|
-
invocation_mode: InvocationMode | None = None
|
|
53
40
|
mcp: SessionMcp = field(init=False)
|
|
54
41
|
|
|
55
42
|
def __post_init__(self) -> None:
|
|
@@ -64,8 +51,6 @@ class McpOAuthSession:
|
|
|
64
51
|
headers[_CONVERSATION_TITLE_HEADER] = self.conversation_title
|
|
65
52
|
if self.last_user_message:
|
|
66
53
|
headers[_LAST_USER_MESSAGE_HEADER] = self.last_user_message
|
|
67
|
-
if self.invocation_mode:
|
|
68
|
-
headers[_INVOCATION_MODE_HEADER] = self.invocation_mode
|
|
69
54
|
self.mcp = SessionMcp(url=f"{base_url()}/v1/mcp", headers=headers)
|
|
70
55
|
|
|
71
56
|
|
|
@@ -122,32 +107,11 @@ class CortexhubMcpOAuthClient:
|
|
|
122
107
|
mcp_session_id: str | None = None,
|
|
123
108
|
conversation_title: str | None = None,
|
|
124
109
|
last_user_message: str | None = None,
|
|
125
|
-
invocation_mode: InvocationMode | None = None,
|
|
126
110
|
refresh: bool = False,
|
|
127
111
|
) -> McpOAuthSession:
|
|
128
|
-
"""Return MCP headers for ``agent`` (required on every call).
|
|
129
|
-
|
|
130
|
-
Pass ``mcp_session_id`` (your chat or conversation id) to group tool
|
|
131
|
-
activity into a single workspace session.
|
|
132
|
-
|
|
133
|
-
Pass ``conversation_title`` and ``last_user_message`` to add context
|
|
134
|
-
that operators can see when reviewing this session in CortexHub
|
|
135
|
-
(sent on every MCP request via headers).
|
|
136
|
-
|
|
137
|
-
Pass ``invocation_mode``:
|
|
138
|
-
|
|
139
|
-
* ``"interactive"`` (default for OAuth callers) -- a human is
|
|
140
|
-
present and can answer in-client consent prompts.
|
|
141
|
-
* ``"autonomous"`` -- cron jobs, queue workers, webhook handlers,
|
|
142
|
-
and other unattended runs. The gateway routes consent through
|
|
143
|
-
configured personal channels instead of expecting a live answer.
|
|
144
|
-
"""
|
|
112
|
+
"""Return MCP headers for ``agent`` (required on every call)."""
|
|
145
113
|
if not agent or not agent.strip():
|
|
146
114
|
raise ValueError("agent= is required.")
|
|
147
|
-
if invocation_mode is not None and invocation_mode not in _VALID_INVOCATION_MODES:
|
|
148
|
-
raise ValueError(
|
|
149
|
-
"invocation_mode must be 'interactive' or 'autonomous'."
|
|
150
|
-
)
|
|
151
115
|
token = self.fetch_token(refresh=refresh)
|
|
152
116
|
session_id = (mcp_session_id or "").strip() or None
|
|
153
117
|
title = (conversation_title or "").strip() or None
|
|
@@ -162,7 +126,6 @@ class CortexhubMcpOAuthClient:
|
|
|
162
126
|
mcp_session_id=session_id,
|
|
163
127
|
conversation_title=title,
|
|
164
128
|
last_user_message=user_message,
|
|
165
|
-
invocation_mode=invocation_mode,
|
|
166
129
|
)
|
|
167
130
|
|
|
168
131
|
|
cortexhub-2.0.5/.gitignore
DELETED
|
@@ -1,104 +0,0 @@
|
|
|
1
|
-
# Python
|
|
2
|
-
__pycache__/
|
|
3
|
-
*.py[cod]
|
|
4
|
-
*$py.class
|
|
5
|
-
*.so
|
|
6
|
-
.Python
|
|
7
|
-
build/
|
|
8
|
-
develop-eggs/
|
|
9
|
-
dist/
|
|
10
|
-
downloads/
|
|
11
|
-
eggs/
|
|
12
|
-
.eggs/
|
|
13
|
-
lib/
|
|
14
|
-
lib64/
|
|
15
|
-
parts/
|
|
16
|
-
sdist/
|
|
17
|
-
var/
|
|
18
|
-
wheels/
|
|
19
|
-
*.egg-info/
|
|
20
|
-
.installed.cfg
|
|
21
|
-
*.egg
|
|
22
|
-
.pytest_cache/
|
|
23
|
-
.ruff_cache/
|
|
24
|
-
.mypy_cache/
|
|
25
|
-
.coverage
|
|
26
|
-
htmlcov/
|
|
27
|
-
.venv/
|
|
28
|
-
venv/
|
|
29
|
-
ENV/
|
|
30
|
-
uv.lock
|
|
31
|
-
|
|
32
|
-
# Rust
|
|
33
|
-
target/
|
|
34
|
-
Cargo.lock
|
|
35
|
-
**/*.rs.bk
|
|
36
|
-
*.pdb
|
|
37
|
-
|
|
38
|
-
# Go
|
|
39
|
-
*.exe
|
|
40
|
-
*.exe~
|
|
41
|
-
*.dll
|
|
42
|
-
*.so
|
|
43
|
-
*.dylib
|
|
44
|
-
*.test
|
|
45
|
-
*.out
|
|
46
|
-
go.work
|
|
47
|
-
vendor/
|
|
48
|
-
|
|
49
|
-
# Java
|
|
50
|
-
target/
|
|
51
|
-
pom.xml.tag
|
|
52
|
-
pom.xml.releaseBackup
|
|
53
|
-
pom.xml.versionsBackup
|
|
54
|
-
pom.xml.next
|
|
55
|
-
release.properties
|
|
56
|
-
dependency-reduced-pom.xml
|
|
57
|
-
buildNumber.properties
|
|
58
|
-
.mvn/timing.properties
|
|
59
|
-
.mvn/wrapper/maven-wrapper.jar
|
|
60
|
-
*.class
|
|
61
|
-
*.jar
|
|
62
|
-
*.war
|
|
63
|
-
*.ear
|
|
64
|
-
hs_err_pid*
|
|
65
|
-
|
|
66
|
-
# TypeScript/JavaScript
|
|
67
|
-
node_modules/
|
|
68
|
-
dist/
|
|
69
|
-
build/
|
|
70
|
-
*.tsbuildinfo
|
|
71
|
-
.turbo/
|
|
72
|
-
.next/
|
|
73
|
-
.cache/
|
|
74
|
-
coverage/
|
|
75
|
-
|
|
76
|
-
# IDE
|
|
77
|
-
.vscode/
|
|
78
|
-
.idea/
|
|
79
|
-
*.swp
|
|
80
|
-
*.swo
|
|
81
|
-
*~
|
|
82
|
-
.DS_Store
|
|
83
|
-
|
|
84
|
-
# Logs
|
|
85
|
-
*.log
|
|
86
|
-
npm-debug.log*
|
|
87
|
-
yarn-debug.log*
|
|
88
|
-
yarn-error.log*
|
|
89
|
-
pnpm-debug.log*
|
|
90
|
-
|
|
91
|
-
# Environment
|
|
92
|
-
.env
|
|
93
|
-
.env.local
|
|
94
|
-
.env.*.local
|
|
95
|
-
.pypirc
|
|
96
|
-
|
|
97
|
-
# OS
|
|
98
|
-
.DS_Store
|
|
99
|
-
Thumbs.db
|
|
100
|
-
python/cortexhub_data
|
|
101
|
-
|
|
102
|
-
.planning/
|
|
103
|
-
.cursor/
|
|
104
|
-
.claude/
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|