@portofcontext/pctx 0.2.2 → 0.3.0

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.
Files changed (4) hide show
  1. package/CHANGELOG.md +29 -3
  2. package/README.md +55 -50
  3. package/npm-shrinkwrap.json +2 -2
  4. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -9,9 +9,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
9
9
 
10
10
  ### Added
11
11
 
12
+ -
13
+
14
+ ### Changed
15
+
16
+ -
12
17
 
13
18
  ### Fixed
14
19
 
20
+ -
21
+
22
+ ## [v0.3.0] - 2025-12-16
23
+
24
+ ### Added
25
+
26
+ - `pctx_session_server` crate implements CodeMode sessions using HTTP endpoints for session management and websockets for code execution with callbacks to user-defined tools.
27
+ - `pctx_core` crate created as the primary code mode library via the `CodeMode` struct. With support for MCP servers and callback functions.
28
+ - `pctx_executor`/`pctx_code_execution_runtime`/`pctx_type_check_runtime` supports callbacks to arbitrary rust callables
29
+ - `pctx-client` (Python) package with `@tool` decorator and `AsyncTool`/`Tool` base class for registering/interacting with the pctx session server. Users can export the CodeMode tools to popular agent frameworks like langchain.
30
+
31
+ ### Changed
32
+
33
+ - **Breaking Change**: `pctx start` now starts the pctx session server, all previous commands have been migrated to `pctx mcp <subcommand>`.
34
+ - `codegen` create extended to include generic `Tool` and `ToolSet` structs and all code generation functions migrated to be methods of these structs.
35
+
36
+ ### Fixed
37
+
38
+ - `[additionalProperty: string]: ...` not included when `additionalProperties: false` in schema.
39
+ - Comments above `[additionalProperty: string]: ...` now correctly document the expected additional property types.
15
40
 
16
41
  ## [v0.2.2] - 2025-12-07
17
42
 
@@ -19,7 +44,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
19
44
 
20
45
  - windows cross-compile support through cargo-dist
21
46
 
22
-
23
47
  ## [v0.2.1] - 2025-11-25
24
48
 
25
49
  ### Added
@@ -34,7 +58,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
34
58
  - Better error state reporting (e.g. invalid config, port already in use)
35
59
  - Scroll out of bounds for tool details panel
36
60
 
37
-
38
61
  ### Changed
39
62
 
40
63
  - Auth type `custom`, changed to `headers` to be more descriptive. `custom` retained as an alias for backwards compatibility
@@ -102,7 +125,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
102
125
 
103
126
  - Initial public release
104
127
 
105
- [Unreleased]: https://github.com/portofcontext/pctx/compare/v0.2.0...HEAD
128
+ [Unreleased]: https://github.com/portofcontext/pctx/compare/v0.3.0...HEAD
129
+ [v0.2.1]: https://github.com/portofcontext/pctx/compare/v0.3.0
130
+ [v0.2.1]: https://github.com/portofcontext/pctx/compare/v0.2.2
131
+ [v0.2.1]: https://github.com/portofcontext/pctx/compare/v0.2.1
106
132
  [v0.2.0]: https://github.com/portofcontext/pctx/compare/v0.2.0
107
133
  [v0.1.4]: https://github.com/portofcontext/pctx/compare/v0.1.4
108
134
  [v0.1.3]: https://github.com/portofcontext/pctx/compare/v0.1.3
package/README.md CHANGED
@@ -5,13 +5,14 @@
5
5
  [![Made by](https://img.shields.io/badge/MADE%20BY-Port%20of%20Context-1e40af.svg?style=for-the-badge&labelColor=0c4a6e)](https://portofcontext.com)
6
6
 
7
7
  [![NPM Version](https://img.shields.io/npm/v/%40portofcontext%2Fpctx)](https://www.npmjs.com/package/@portofcontext/pctx)
8
- [![Rust](https://img.shields.io/badge/rust-1.89%2B-blue.svg)](https://www.rust-lang.org)
8
+ [![Rust](https://img.shields.io/badge/rust-1.89%2B-green.svg)](https://www.rust-lang.org)
9
+ [![Python](https://img.shields.io/pypi/v/pctx-client?color=blue)](https://pctx.readthedocs.io/en/latest/)
9
10
 
10
11
  </div>
11
12
 
12
13
  <div align="center">
13
14
 
14
- The open source framework to connect AI agents to tools and services with [code mode](#what-is-code-mode)
15
+ The open source framework to connect AI agents to tools and mcp with [Code Mode](#what-is-code-mode)
15
16
 
16
17
  </div>
17
18
 
@@ -28,20 +29,63 @@ curl --proto '=https' --tlsv1.2 -LsSf https://raw.githubusercontent.com/portofco
28
29
  npm i -g @portofcontext/pctx
29
30
  ```
30
31
 
31
- ## Quick Start
32
+ ## Core Functionality
33
+ pctx can be run as a stateless HTTP server for Code Mode sessions or as a unified MCP server that exposes Code Mode functionality for registered upstream MCP servers.
34
+
35
+ ```bash
36
+ # Start Code Mode for Python SDK
37
+ pctx start
38
+
39
+ # Start Code Mode as a unified MCP server
40
+ pctx mcp init
41
+ pctx mcp dev
42
+ ```
43
+
44
+ ## Python SDK
45
+ Use the Python SDK if building agents in Python and want to run Code Mode with custom tools and/or MCP servers. The Python SDK is an HTTP client to the `pctx` server.
46
+ ```bash
47
+ uv pip install pctx-client
48
+ ```
49
+ ```python
50
+ from pctx_client import Pctx, tool
51
+ from agents import Agent # Use any Agent SDK
52
+ from agents.run import Runner # This example is OpenAI Agents SDK
53
+
54
+ @tool
55
+ def get_weather(city: str) -> str:
56
+ """Get weather information for a given city."""
57
+ return f"It's always sunny in {city}!"
58
+
59
+ pctx = Pctx(tools=[get_weather]) # or with mcp: servers=[your_mcp]
60
+
61
+ tools = pctx.openai_agents_tools() # Run Code Mode with any Agent SDK
62
+ agent = Agent(
63
+ name="GreatCoder",
64
+ model="litellm/openrouter/openai/gpt-oss-120b",
65
+ instructions="You run code to complete complex tasks.",
66
+ tools=tools,
67
+ )
68
+ ```
69
+ Complete Docs: [Python SDK Quickstart and Docs](./pctx-py/README.md)
70
+
71
+ ## Node SDK
72
+ Coming soon
73
+
74
+ ## Unified MCP
75
+ Use the unified MCP to run Code Mode with MCP servers and want to persist the authentication connections and you do not need to register local tools.
32
76
 
33
77
  ```bash
34
78
  # Initialize config for upstream mcp connections
35
- pctx init
79
+ pctx mcp init
36
80
 
37
81
  # Connect to any MCP server
38
- pctx add my-local-server http://localhost:3000/mcp
39
- pctx add stripe https://mcp.stripe.com
82
+ pctx mcp add my-local-server http://localhost:3000/mcp
83
+ pctx mcp add stripe https://mcp.stripe.com
40
84
 
41
85
  # Start the unified MCP server in dev mode
42
- pctx dev
86
+ pctx mcp dev
43
87
 
44
- # copy the pctx url and connect to agents with --transport http
88
+ # copy server url and connect to agents with --transport http
45
89
  ```
46
90
 
47
91
  For complete CLI documentation, see [CLI.md](docs/CLI.md).
@@ -49,14 +93,13 @@ For configuration options, see [Configuration Guide](docs/config.md).
49
93
 
50
94
  <img width="1020" height="757" alt="Screenshot 2025-11-21 at 11 03 20 AM" src="https://github.com/user-attachments/assets/d61be46d-5a4b-40fd-953a-7dc725266e63" />
51
95
 
52
-
53
96
  ## What is pctx?
54
97
 
55
98
  `pctx` sits between AI agents and MCP servers. It aggregates multiple upstream MCP servers, handles authentication, and exposes tools through a unified [Code Mode](#what-is-code-mode) interface. Instead of agents managing connections to individual MCP servers, they connect once to pctx.
56
99
 
57
100
  ## What is Code Mode?
58
101
 
59
- Code mode replaces sequential tool calling with code execution. Rather than an agent calling tools one at a time and passing results through its context window, it writes TypeScript code that executes in a sandbox. Read Anthropic's overview [here](https://www.anthropic.com/engineering/code-execution-with-mcp).
102
+ Code mode replaces sequential tool calling with code execution. Rather than an agent calling tools one at a time and passing results through its context window, it writes code that executes in a sandbox. Read Anthropic's overview [here](https://www.anthropic.com/engineering/code-execution-with-mcp).
60
103
 
61
104
  **Traditional MCP flow**:
62
105
 
@@ -77,51 +120,13 @@ console.log(`Found ${orders.length} orders`);
77
120
 
78
121
  ## Features
79
122
 
80
- - **Code Mode interface**: Tools exposed as TypeScript functions for efficient agent interaction. See [Code Mode Guide](docs/code-mode.md).
123
+ - **Code Mode interface**: Tools exposed as code functions for efficient agent interaction. See [Code Mode Guide](docs/code-mode.md).
81
124
  - **Upstream MCP server aggregation**: Connect to multiple MCP servers through a single interface. See [Upstream MCP Servers Guide](docs/upstream-mcp-servers.md).
82
125
  - **Simple config with CLI**: Create the pctx.json config with a simple CLI. pctx.json manages auth, upstream MCPs, logging, and more. See [Config Guide](docs/config.md).
83
126
  - **Secure authentication**: Source secrets from environment variables, system keychain, and external commands. See [Authentication Section](docs/config.md#authentication) in the CLI configuration docs for more details.
84
127
 
85
128
  ## Architecture
86
-
87
- ```
88
- Runs locally • in docker • any cloud
89
-
90
- ┌─────────────────────────────────┐
91
- │ AI Agents (Bring any LLM) │
92
- └──────────────-──────────────────┘
93
- │ MCP
94
- │ • list_functions
95
- │ • get_function_details
96
- │ • execute
97
- ┌─────────────▼───────────────────┐
98
- │ pctx │
99
- │ │
100
- │ ┌─────────────────────────┐ │
101
- │ │ TypeScript Compiler │ │
102
- │ │ Sandbox (Deno) │ │
103
- │ │ │ │
104
- │ │ • Type checking │ │
105
- │ │ • Rich error feedback │ │
106
- │ │ • No network access │ │
107
- │ └──────────┬──────────────┘ │
108
- │ │ Compiled JS │
109
- │ ┌──────────▼──────────────┐ │
110
- │ │ Execution Sandbox │ │
111
- │ │ (Deno Runtime) │ │
112
- │ │ │ │
113
- │ │ • Authenticated MCP │ │
114
- │ │ client connections │ │
115
- │ │ • Restricted network │ │
116
- │ │ • Tool call execution │ │
117
- │ └──┬──────┬──────┬────────┘ │
118
- └─────┼──────┼──────┼─────────────┘
119
- │ │ │
120
- ↓ ↓ ↓
121
- ┌──────┬──────┬──────┬──────┐
122
- │Local │Slack │GitHub│Custom│
123
- └──────┴──────┴──────┴──────┘
124
- ```
129
+ <img width="1020" height="757" alt="Screenshot 2025-11-21 at 11 03 20 AM" src="./docs/pctx-architecture.svg" />
125
130
 
126
131
  ## Security
127
132
 
package/npm-shrinkwrap.json CHANGED
@@ -24,7 +24,7 @@
24
24
  "hasInstallScript": true,
25
25
  "license": "MIT",
26
26
  "name": "@portofcontext/pctx",
27
- "version": "0.2.2"
27
+ "version": "0.3.0"
28
28
  },
29
29
  "node_modules/@isaacs/balanced-match": {
30
30
  "engines": {
@@ -897,5 +897,5 @@
897
897
  }
898
898
  },
899
899
  "requires": true,
900
- "version": "0.2.2"
900
+ "version": "0.3.0"
901
901
  }
package/package.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
- "artifactDownloadUrl": "https://github.com/portofcontext/pctx/releases/download/v0.2.2",
2
+ "artifactDownloadUrl": "https://github.com/portofcontext/pctx/releases/download/v0.3.0",
3
3
  "bin": {
4
4
  "generate-cli-docs": "run-generate-cli-docs.js",
5
5
  "pctx": "run-pctx.js"
@@ -92,7 +92,7 @@
92
92
  "zipExt": ".tar.gz"
93
93
  }
94
94
  },
95
- "version": "0.2.2",
95
+ "version": "0.3.0",
96
96
  "volta": {
97
97
  "node": "18.14.1",
98
98
  "npm": "9.5.0"