Skip to content

v1.0 #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 24, 2025
Merged

v1.0 #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1b528be
Update toDict from core
h3xxit Oct 22, 2025
c5328aa
Dont replace varialbes in strings with $ref
h3xxit Oct 22, 2025
264c310
Fix a lot of issues
h3xxit Oct 23, 2025
42035a1
Update update-versions.js
h3xxit Oct 23, 2025
82390c1
Fix tests
h3xxit Oct 23, 2025
d13bade
Fix more issues
h3xxit Oct 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 40 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ UTCP offers a unified framework for integrating disparate tools and services, ma
* **Automatic Plugin Registration**: The official plugins are automatically discovered and registered when you import the core client—no manual setup required. For other plugins, you will need to register them manually.
* **Scalability**: Designed to handle a large number of tools and providers without compromising performance.
* **Extensibility**: A pluggable architecture allows developers to easily add new communication protocols, tool storage mechanisms, and search strategies without modifying the core library.
* **Interoperability**: With a growing ecosystem of protocol plugins—including HTTP, MCP, Text, and CLI—UTCP can integrate with almost any existing service or infrastructure.
* **Interoperability**: With a growing ecosystem of protocol plugins—including HTTP, MCP, Text, File, and CLI—UTCP can integrate with almost any existing service or infrastructure.
* **Type Safety**: Built on well-defined TypeScript interfaces and runtime validation powered by Zod, making it robust and developer-friendly.
* **Secure Variable Management**: Namespace-isolated variables prevent leakage between manuals, with support for environment variables and .env files.

Expand All @@ -28,10 +28,13 @@ Install UTCP packages from npm:

```bash
# Install core SDK and desired protocol plugins
npm install @utcp/sdk @utcp/http @utcp/mcp @utcp/text
npm install @utcp/sdk @utcp/http @utcp/mcp @utcp/text @utcp/file

# Optional: Add dotenv variable loader for Node.js
npm install @utcp/dotenv-loader

# Or using bun
bun add @utcp/sdk @utcp/http @utcp/mcp @utcp/text
bun add @utcp/sdk @utcp/http @utcp/mcp @utcp/text @utcp/file
```

### For Development
Expand Down Expand Up @@ -98,13 +101,13 @@ main().catch(console.error);
import { UtcpClient } from '@utcp/sdk';
import { HttpCallTemplateSerializer } from '@utcp/http';
import { McpCallTemplateSerializer } from '@utcp/mcp';
import { TextCallTemplateSerializer } from '@utcp/text';
import { FileCallTemplateSerializer } from '@utcp/file';
Copy link
Contributor

@cubic-dev-ai cubic-dev-ai bot Oct 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Quick Start example now relies on the dotenv variable loader, but there is still no import '@utcp/dotenv-loader';, so the loader never registers and UtcpClient.create will fail to resolve the dotenv loader at runtime. Please add the side-effect import alongside the other plugin imports.

Prompt for AI agents 
Address the following comment on README.md at line 104:

<comment>The Quick Start example now relies on the dotenv variable loader, but there is still no `import &#39;@utcp/dotenv-loader&#39;;`, so the loader never registers and `UtcpClient.create` will fail to resolve the `dotenv` loader at runtime. Please add the side-effect import alongside the other plugin imports.</comment>

<file context>
@@ -98,13 +101,13 @@ main().catch(console.error);
 import { HttpCallTemplateSerializer } from &#39;@utcp/http&#39;;
 import { McpCallTemplateSerializer } from &#39;@utcp/mcp&#39;;
-import { TextCallTemplateSerializer } from &#39;@utcp/text&#39;;
+import { FileCallTemplateSerializer } from &#39;@utcp/file&#39;;
 
 async function main() {
</file context>
Fix with Cubic


async function main() {
// Create serializers for each protocol
const httpSerializer = new HttpCallTemplateSerializer();
const mcpSerializer = new McpCallTemplateSerializer();
const textSerializer = new TextCallTemplateSerializer();
const fileSerializer = new FileCallTemplateSerializer();

// Validate and create call templates
const httpTemplate = httpSerializer.validateDict({
Expand Down Expand Up @@ -132,9 +135,9 @@ async function main() {
}
});

const textTemplate = textSerializer.validateDict({
const fileTemplate = fileSerializer.validateDict({
name: 'local_tools',
call_template_type: 'text',
call_template_type: 'file',
file_path: './config/tools.json'
});

Expand All @@ -152,7 +155,7 @@ async function main() {
manual_call_templates: [
httpTemplate, // HTTP API
mcpTemplate, // MCP Server
textTemplate // Local file-based tools
fileTemplate // Local file-based tools
]
});

Expand Down Expand Up @@ -383,15 +386,34 @@ const mcpTemplate = serializer.validateDict({

### Text Protocol

Load tools from local JSON/YAML files or OpenAPI specs:
Handle direct text/string content (browser-compatible):

```typescript
import { TextCallTemplateSerializer } from '@utcp/text';

const serializer = new TextCallTemplateSerializer();
const textTemplate = serializer.validateDict({
name: 'local_tools',
name: 'inline_tools',
call_template_type: 'text',
content: JSON.stringify({
tools: [
// UTCP manual or OpenAPI spec as string
]
})
});
```

### File Protocol

Load tools from local JSON/YAML files or OpenAPI specs (Node.js only):

```typescript
import { FileCallTemplateSerializer } from '@utcp/file';

const serializer = new FileCallTemplateSerializer();
const fileTemplate = serializer.validateDict({
name: 'local_tools',
call_template_type: 'file',
file_path: './config/tools.json'
// Supports: .json, .yaml, .yml, OpenAPI specs
});
Expand Down Expand Up @@ -425,7 +447,10 @@ typescript-utcp/
│ ├── core/ # Core SDK with UtcpClient and interfaces
│ ├── http/ # HTTP protocol plugin
│ ├── mcp/ # MCP protocol plugin
│ ├── text/ # Text/file protocol plugin
│ ├── text/ # Text/string content protocol plugin (browser-compatible)
│ ├── file/ # File system protocol plugin (Node.js only)
│ ├── dotenv-loader/ # DotEnv variable loader plugin (Node.js only)
│ ├── direct-call/ # Direct call protocol plugin
│ └── cli/ # CLI protocol plugin
├── tests/ # End-to-end integration tests
└── README.md
Expand All @@ -435,7 +460,10 @@ Each package is independently published to npm:
- `@utcp/sdk` - Core SDK library (required)
- `@utcp/http` - HTTP protocol support
- `@utcp/mcp` - MCP protocol support
- `@utcp/text` - File-based tools
- `@utcp/text` - Direct text/string content (browser-compatible)
- `@utcp/file` - File system operations (Node.js only)
- `@utcp/dotenv-loader` - DotEnv variable loader (Node.js only)
- `@utcp/direct-call` - Direct function call protocol
- `@utcp/cli` - Command-line tools

## Development & Testing
Expand Down
62 changes: 50 additions & 12 deletions bun.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
},
"packages/cli": {
"name": "@utcp/cli",
"version": "1.0.4",
"version": "1.0.6",
"dependencies": {
"@utcp/sdk": "^1.0.4",
},
Expand All @@ -29,7 +29,7 @@
},
"packages/core": {
"name": "@utcp/sdk",
"version": "1.0.5",
"version": "1.0.8",
"dependencies": {
"dotenv": "^17.2.1",
"zod": "^3.23.8",
Expand All @@ -41,7 +41,7 @@
},
"packages/direct-call": {
"name": "@utcp/direct-call",
"version": "1.0.0",
"version": "1.0.1",
"dependencies": {
"@utcp/sdk": "^1.0.4",
},
Expand All @@ -51,11 +51,40 @@
"typescript": "^5.0.0",
},
},
"packages/dotenv-loader": {
"name": "@utcp/dotenv-loader",
"version": "1.0.0",
"dependencies": {
"dotenv": "^17.2.1",
"zod": "^3.23.8",
},
"devDependencies": {
"bun-types": "latest",
"typescript": "^5.0.0",
},
"peerDependencies": {
"@utcp/sdk": "^1.0.8",
},
},
"packages/file": {
"name": "@utcp/file",
"version": "1.0.0",
"dependencies": {
"@utcp/http": "^1.0.7",
"@utcp/sdk": "^1.0.8",
"js-yaml": "^4.1.0",
},
"devDependencies": {
"@types/bun": "latest",
"bun-types": "latest",
"typescript": "^5.0.0",
},
},
"packages/http": {
"name": "@utcp/http",
"version": "1.0.4",
"version": "1.0.8",
"dependencies": {
"@utcp/sdk": "^1.0.4",
"@utcp/sdk": "^1.0.6",
"axios": "^1.11.0",
"js-yaml": "^4.1.0",
},
Expand All @@ -67,7 +96,7 @@
},
"packages/mcp": {
"name": "@utcp/mcp",
"version": "1.0.4",
"version": "1.0.6",
"dependencies": {
"@modelcontextprotocol/sdk": "^1.17.4",
"@utcp/sdk": "^1.0.4",
Expand All @@ -82,12 +111,13 @@
},
"packages/text": {
"name": "@utcp/text",
"version": "1.0.4",
"version": "1.0.11",
"dependencies": {
"@utcp/sdk": "^1.0.4",
"@utcp/http": "^1.0.8",
"@utcp/sdk": "^1.0.8",
"js-yaml": "^4.1.0",
},
"devDependencies": {
"@types/bun": "latest",
"bun-types": "latest",
"typescript": "^5.0.0",
},
Expand Down Expand Up @@ -229,6 +259,10 @@

"@utcp/direct-call": ["@utcp/direct-call@workspace:packages/direct-call"],

"@utcp/dotenv-loader": ["@utcp/dotenv-loader@workspace:packages/dotenv-loader"],

"@utcp/file": ["@utcp/file@workspace:packages/file"],

"@utcp/http": ["@utcp/http@workspace:packages/http"],

"@utcp/mcp": ["@utcp/mcp@workspace:packages/mcp"],
Expand Down Expand Up @@ -591,13 +625,17 @@

"@utcp/direct-call/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-u8X0thhx+yJ0KmkxuEo9HAtdfgCBaM/aI9K90VQcQioAmkVp3SG3FkwWGibUFz3WdXAdcsqOcbU40lK7tbHdkQ=="],

"@utcp/http/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-u8X0thhx+yJ0KmkxuEo9HAtdfgCBaM/aI9K90VQcQioAmkVp3SG3FkwWGibUFz3WdXAdcsqOcbU40lK7tbHdkQ=="],
"@utcp/dotenv-loader/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-NMrcy7smratanWJ2mMXdpatalovtxVggkj11bScuWuiOoXTiKIu2eVS1/7qbyI/4yHedtsn175n4Sm4JcdHLXw=="],

"@utcp/file/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-NMrcy7smratanWJ2mMXdpatalovtxVggkj11bScuWuiOoXTiKIu2eVS1/7qbyI/4yHedtsn175n4Sm4JcdHLXw=="],

"@utcp/http/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-NMrcy7smratanWJ2mMXdpatalovtxVggkj11bScuWuiOoXTiKIu2eVS1/7qbyI/4yHedtsn175n4Sm4JcdHLXw=="],

"@utcp/mcp/bun-types": ["[email protected]", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-u8X0thhx+yJ0KmkxuEo9HAtdfgCBaM/aI9K90VQcQioAmkVp3SG3FkwWGibUFz3WdXAdcsqOcbU40lK7tbHdkQ=="],

"@utcp/sdk/bun-types": ["[email protected].0", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-u8X0thhx+yJ0KmkxuEo9HAtdfgCBaM/aI9K90VQcQioAmkVp3SG3FkwWGibUFz3WdXAdcsqOcbU40lK7tbHdkQ=="],
"@utcp/sdk/bun-types": ["[email protected].1", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-NMrcy7smratanWJ2mMXdpatalovtxVggkj11bScuWuiOoXTiKIu2eVS1/7qbyI/4yHedtsn175n4Sm4JcdHLXw=="],

"@utcp/text/bun-types": ["[email protected].0", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-u8X0thhx+yJ0KmkxuEo9HAtdfgCBaM/aI9K90VQcQioAmkVp3SG3FkwWGibUFz3WdXAdcsqOcbU40lK7tbHdkQ=="],
"@utcp/text/bun-types": ["[email protected].1", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-NMrcy7smratanWJ2mMXdpatalovtxVggkj11bScuWuiOoXTiKIu2eVS1/7qbyI/4yHedtsn175n4Sm4JcdHLXw=="],

"accepts/mime-types": ["[email protected]", "", { "dependencies": { "mime-db": "^1.54.0" } }, "sha512-xRc4oEhT6eaBpU1XF7AjpOFD+xQmXNB5OVKwp4tqCuBpHLS/ZbBDrc07mYTDqVMg6PfxUjjNp85O6Cd2Z/5HWA=="],

Expand Down
Loading