@portofcontext/pctx 0.2.2 → 0.4.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 +44 -3
  2. package/README.md +73 -51
  3. package/npm-shrinkwrap.json +2 -2
  4. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -9,9 +9,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
9
9
 
10
10
  ### Added
11
11
 
12
+ ### Changed
13
+
14
+ ### Fixed
15
+
16
+ ## [v0.4.0] - 2025-12-31
17
+
18
+ ### Added
19
+
20
+ - Stdio MCP server support for upstreams via `pctx.json` (`command`, `args`, `env`).
21
+ - `pctx mcp add` now supports stdio MCP servers via `--command`, `--arg`, and `--env` flags.
22
+ - `pctx mcp start --stdio` to serve the MCP interface over stdio.
23
+ - Logger configuration now supports optional `file` field to write logs to a file.
24
+
25
+ ### Changed
26
+
27
+ - `pctx mcp add` now accepts either a URL (for HTTP servers) or `--command` (for stdio servers), making it a unified interface for adding all types of MCP servers.
28
+ - Logger output behavior is now mode-aware to ensure stdio compatibility:
29
+ - `--stdio` mode without `logger.file`: logging is automatically disabled to keep stdout/stderr clean for JSON-RPC communication
30
+ - `--stdio` mode with `logger.file`: logs write to the specified file
31
+ - HTTP mode: logs write to stdout (default behavior)
32
+
33
+ ### Fixed
34
+
35
+ - Improved error handling for stdio config and MCP initialization failures.
36
+
37
+ ## [v0.3.0] - 2025-12-16
38
+
39
+ ### Added
40
+
41
+ - `pctx_session_server` crate implements CodeMode sessions using HTTP endpoints for session management and websockets for code execution with callbacks to user-defined tools.
42
+ - `pctx_core` crate created as the primary code mode library via the `CodeMode` struct. With support for MCP servers and callback functions.
43
+ - `pctx_executor`/`pctx_code_execution_runtime`/`pctx_type_check_runtime` supports callbacks to arbitrary rust callables
44
+ - `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.
45
+
46
+ ### Changed
47
+
48
+ - **Breaking Change**: `pctx start` now starts the pctx session server, all previous commands have been migrated to `pctx mcp <subcommand>`.
49
+ - `codegen` create extended to include generic `Tool` and `ToolSet` structs and all code generation functions migrated to be methods of these structs.
12
50
 
13
51
  ### Fixed
14
52
 
53
+ - `[additionalProperty: string]: ...` not included when `additionalProperties: false` in schema.
54
+ - Comments above `[additionalProperty: string]: ...` now correctly document the expected additional property types.
15
55
 
16
56
  ## [v0.2.2] - 2025-12-07
17
57
 
@@ -19,7 +59,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
19
59
 
20
60
  - windows cross-compile support through cargo-dist
21
61
 
22
-
23
62
  ## [v0.2.1] - 2025-11-25
24
63
 
25
64
  ### Added
@@ -34,7 +73,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
34
73
  - Better error state reporting (e.g. invalid config, port already in use)
35
74
  - Scroll out of bounds for tool details panel
36
75
 
37
-
38
76
  ### Changed
39
77
 
40
78
  - Auth type `custom`, changed to `headers` to be more descriptive. `custom` retained as an alias for backwards compatibility
@@ -102,7 +140,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
102
140
 
103
141
  - Initial public release
104
142
 
105
- [Unreleased]: https://github.com/portofcontext/pctx/compare/v0.2.0...HEAD
143
+ [Unreleased]: https://github.com/portofcontext/pctx/compare/v0.3.0...HEAD
144
+ [v0.2.1]: https://github.com/portofcontext/pctx/compare/v0.3.0
145
+ [v0.2.1]: https://github.com/portofcontext/pctx/compare/v0.2.2
146
+ [v0.2.1]: https://github.com/portofcontext/pctx/compare/v0.2.1
106
147
  [v0.2.0]: https://github.com/portofcontext/pctx/compare/v0.2.0
107
148
  [v0.1.4]: https://github.com/portofcontext/pctx/compare/v0.1.4
108
149
  [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,74 @@ 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
+
34
+ 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.
35
+
36
+ ```bash
37
+ # Start Code Mode for Python SDK
38
+ pctx start
39
+
40
+ # Start Code Mode as a unified MCP server
41
+ pctx mcp init
42
+ pctx mcp dev
43
+ ```
44
+
45
+ ## Python SDK
46
+
47
+ 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.
48
+
49
+ ```bash
50
+ pip install pctx-client
51
+ ```
52
+
53
+ ```python
54
+ from pctx_client import Pctx, tool
55
+ from agents import Agent # Use any Agent SDK
56
+ from agents.run import Runner # This example is OpenAI Agents SDK
57
+
58
+ @tool
59
+ def get_weather(city: str) -> str:
60
+ """Get weather information for a given city."""
61
+ return f"It's always sunny in {city}!"
62
+
63
+ pctx = Pctx(tools=[get_weather]) # or with mcp: servers=[your_mcp]
64
+
65
+ tools = pctx.openai_agents_tools() # Run Code Mode with any Agent SDK
66
+ agent = Agent(
67
+ name="GreatCoder",
68
+ model="litellm/openrouter/openai/gpt-oss-120b",
69
+ instructions="You run code to complete complex tasks.",
70
+ tools=tools,
71
+ )
72
+ ```
73
+
74
+ ### Links
75
+
76
+ - [Python SDK Quickstart and Docs](./pctx-py/README.md)
77
+ - [Python API Reference](https://pctx.readthedocs.io/en/latest/)
78
+
79
+ ## Node SDK
80
+
81
+ Coming soon
82
+
83
+ ## Unified MCP
84
+
85
+ Use the unified MCP to run Code Mode with MCP servers and want to persist the authentication connections and you do not need to use agent tools (non-mcp tools).
32
86
 
33
87
  ```bash
34
88
  # Initialize config for upstream mcp connections
35
- pctx init
89
+ pctx mcp init
36
90
 
37
- # Connect to any MCP server
38
- pctx add my-local-server http://localhost:3000/mcp
39
- pctx add stripe https://mcp.stripe.com
91
+ # Add HTTP or stdio MCP servers
92
+ pctx mcp add stripe https://mcp.stripe.com
93
+ pctx mcp add memory --command "npx -y @modelcontextprotocol/server-memory"
40
94
 
41
- # Start the unified MCP server in dev mode
42
- pctx dev
95
+ # Start as HTTP server (dev mode with UI)
96
+ pctx mcp dev
43
97
 
44
- # copy the pctx url and connect to agents with --transport http
98
+ # Or start as stdio MCP server
99
+ pctx mcp start --stdio
45
100
  ```
46
101
 
47
102
  For complete CLI documentation, see [CLI.md](docs/CLI.md).
@@ -49,14 +104,13 @@ For configuration options, see [Configuration Guide](docs/config.md).
49
104
 
50
105
  <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
106
 
52
-
53
107
  ## What is pctx?
54
108
 
55
109
  `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
110
 
57
111
  ## What is Code Mode?
58
112
 
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).
113
+ 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
114
 
61
115
  **Traditional MCP flow**:
62
116
 
@@ -77,51 +131,14 @@ console.log(`Found ${orders.length} orders`);
77
131
 
78
132
  ## Features
79
133
 
80
- - **Code Mode interface**: Tools exposed as TypeScript functions for efficient agent interaction. See [Code Mode Guide](docs/code-mode.md).
134
+ - **Code Mode interface**: Tools exposed as code functions for efficient agent interaction. See [Code Mode Guide](docs/code-mode.md).
81
135
  - **Upstream MCP server aggregation**: Connect to multiple MCP servers through a single interface. See [Upstream MCP Servers Guide](docs/upstream-mcp-servers.md).
82
136
  - **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
137
  - **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
138
 
85
139
  ## Architecture
86
140
 
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
- ```
141
+ <img width="1020" height="757" alt="Screenshot 2025-11-21 at 11 03 20 AM" src="./docs/pctx-architecture.svg" />
125
142
 
126
143
  ## Security
127
144
 
@@ -145,6 +162,11 @@ npm upgrade -g @portofcontext/pctx
145
162
 
146
163
  ```
147
164
 
165
+ ## Develop
166
+
167
+ - For core dev: install rust and jump into `crates/`
168
+ - Client SDK dev: find the README in the SDK
169
+
148
170
  ## Learn More
149
171
 
150
172
  - [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
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.4.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.4.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.4.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.4.0",
96
96
  "volta": {
97
97
  "node": "18.14.1",
98
98
  "npm": "9.5.0"