{"_id":"@alexma03/utcp-file","_rev":"3-fadb6e994d08c16d4e95c0f401a04938","name":"@alexma03/utcp-file","dist-tags":{"latest":"1.1.2"},"versions":{"1.1.0":{"name":"@alexma03/utcp-file","version":"1.1.0","keywords":["utcp","universal-tool-calling-protocol","tools","api","typescript","tool calling","file","agent","ai","llm"],"author":{"name":"Alexma03"},"license":"MPL-2.0","_id":"@alexma03/utcp-file@1.1.0","maintainers":[{"name":"alexma03","email":"alex03marcos@gmail.com"}],"homepage":"https://github.com/Alexma03/alexma03-utcp#readme","bugs":{"url":"https://github.com/Alexma03/alexma03-utcp/issues"},"dist":{"shasum":"415223fc45ad29c4688a360efc563e24520e6cab","tarball":"https://registry.npmjs.org/@alexma03/utcp-file/-/utcp-file-1.1.0.tgz","fileCount":8,"integrity":"sha512-gWPGgQh1Ntg+GtY1vKv1Sy/URue00uFFkrl5yoTU51qFcdzaUSrOMeP1PV+pYICVtznuOlfb69/n9ZN/NRlozw==","signatures":[{"sig":"MEUCIH759vi0E711a3tESEXmzGXizclJY4JyxoWqDEHj+naAAiEA00m0b4qOWBzE03rCD4udmkhFxIkBBR8cFhM4pi3LY5k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":779219},"main":"dist/index.cjs","type":"module","types":"dist/index.d.ts","module":"dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"97f8055784030184a8917378a6de581d7ae7f22d","scripts":{"build":"tsup"},"_npmUser":{"name":"alexma03","email":"alex03marcos@gmail.com"},"repository":{"url":"git+https://github.com/Alexma03/alexma03-utcp.git","type":"git","directory":"packages/file"},"_npmVersion":"11.9.0","description":"File system protocol for UTCP - reads UTCP manuals from local files (Node.js only)","directories":{},"_nodeVersion":"24.14.0","dependencies":{"js-yaml":"^4.1.0","@alexma03/utcp-sdk":"workspace:*","@alexma03/utcp-http":"workspace:*"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"bun-types":"latest","@types/bun":"latest","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/utcp-file_1.1.0_1773650836110_0.9352050774680492","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"name":"@alexma03/utcp-file","version":"1.1.1","keywords":["utcp","universal-tool-calling-protocol","tools","api","typescript","tool calling","file","agent","ai","llm"],"author":{"name":"Alexma03"},"license":"MPL-2.0","_id":"@alexma03/utcp-file@1.1.1","maintainers":[{"name":"alexma03","email":"alex03marcos@gmail.com"}],"homepage":"https://github.com/Alexma03/alexma03-utcp#readme","bugs":{"url":"https://github.com/Alexma03/alexma03-utcp/issues"},"dist":{"shasum":"7ad2c0c298ba0c906e8c3e871a607dc64cfc7718","tarball":"https://registry.npmjs.org/@alexma03/utcp-file/-/utcp-file-1.1.1.tgz","fileCount":8,"integrity":"sha512-0Shm620NAt4vqo3ngZlpt2OZjD5j3V73GftdQA1ipQjW6t9zbMrqA0BiTmTmEloQavoMEIiUPbvsSYpQq1z7FA==","signatures":[{"sig":"MEUCIQC7lKaklvT9ahj8fPW7b+jb/SRCdlfCceQAjsG/onVJwQIgSuhRMcjgtZQD1Fv3OUEHnXuLWwD2tIKDL6qx9Pm2pos=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":779209},"main":"dist/index.cjs","type":"module","types":"dist/index.d.ts","module":"dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"e836da75819768e8584255bfb61e7bdee947b035","scripts":{"build":"tsup"},"_npmUser":{"name":"alexma03","email":"alex03marcos@gmail.com"},"repository":{"url":"git+https://github.com/Alexma03/alexma03-utcp.git","type":"git","directory":"packages/file"},"_npmVersion":"11.9.0","description":"File system protocol for UTCP - reads UTCP manuals from local files (Node.js only)","directories":{},"_nodeVersion":"24.14.0","dependencies":{"js-yaml":"^4.1.0","@alexma03/utcp-sdk":"^1.1.0","@alexma03/utcp-http":"^1.1.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"bun-types":"latest","@types/bun":"latest","typescript":"^5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/utcp-file_1.1.1_1773651926277_0.7303711918551925","host":"s3://npm-registry-packages-npm-production"}},"1.1.2":{"name":"@alexma03/utcp-file","version":"1.1.2","description":"File system protocol for UTCP - reads UTCP manuals from local files (Node.js only)","main":"dist/index.cjs","module":"dist/index.js","types":"dist/index.d.ts","type":"module","license":"MPL-2.0","author":{"name":"Alexma03"},"repository":{"type":"git","url":"git+https://github.com/Alexma03/alexma03-utcp.git","directory":"packages/file"},"homepage":"https://github.com/Alexma03/alexma03-utcp#readme","bugs":{"url":"https://github.com/Alexma03/alexma03-utcp/issues"},"keywords":["utcp","universal-tool-calling-protocol","tools","api","typescript","tool calling","file","agent","ai","llm"],"publishConfig":{"access":"public"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs","default":"./dist/index.js"}},"dependencies":{"@alexma03/utcp-sdk":"^1.1.1","@alexma03/utcp-http":"^1.1.3","js-yaml":"^4.1.0"},"devDependencies":{"@types/jest":"29.5.12","@types/node":"20.0.0","jest":"29.7.0","ts-jest":"29.1.2","typescript":"^5.0.0"},"scripts":{"build":"tsup","test":"jest"},"_id":"@alexma03/utcp-file@1.1.2","_integrity":"sha512-KD1UyNz+d5Sd71f7962d05MJVH0waXD8vHLLfb3YkrslnSOe0KhV0jwCQERDw2ja9cGzvnIxR764TK2ap6pH+A==","_resolved":"/private/var/folders/mw/dp007xzd5sz9vkhkjfz0fdh40000gn/T/72ca136f8381af994b463536f6aac83e/alexma03-utcp-file-1.1.2.tgz","_from":"file:alexma03-utcp-file-1.1.2.tgz","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-KD1UyNz+d5Sd71f7962d05MJVH0waXD8vHLLfb3YkrslnSOe0KhV0jwCQERDw2ja9cGzvnIxR764TK2ap6pH+A==","shasum":"9bbfba314c4e2db2013d49c1e6279d19ab03ecc2","tarball":"https://registry.npmjs.org/@alexma03/utcp-file/-/utcp-file-1.1.2.tgz","fileCount":8,"unpackedSize":779580,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDqE6FOaFr93mqVlslAS5jheAjmjEdQrycR/YDTiLifNwIgTpUYH4yNZTOtNixo6dPZlQ9ZsHyfzlvZp5IQuK/5ycc="}]},"_npmUser":{"name":"alexma03","email":"alex03marcos@gmail.com"},"directories":{},"maintainers":[{"name":"alexma03","email":"alex03marcos@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/utcp-file_1.1.2_1773735255535_0.054450881687792885"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-16T08:47:15.951Z","modified":"2026-03-17T08:14:15.813Z","1.1.0":"2026-03-16T08:47:16.254Z","1.1.1":"2026-03-16T09:05:26.448Z","1.1.2":"2026-03-17T08:14:15.694Z"},"bugs":{"url":"https://github.com/Alexma03/alexma03-utcp/issues"},"author":{"name":"Alexma03"},"license":"MPL-2.0","homepage":"https://github.com/Alexma03/alexma03-utcp#readme","keywords":["utcp","universal-tool-calling-protocol","tools","api","typescript","tool calling","file","agent","ai","llm"],"repository":{"type":"git","url":"git+https://github.com/Alexma03/alexma03-utcp.git","directory":"packages/file"},"description":"File system protocol for UTCP - reads UTCP manuals from local files (Node.js only)","maintainers":[{"name":"alexma03","email":"alex03marcos@gmail.com"}],"readme":"# @alexma03/utcp-file: File System Communication Protocol Plugin for UTCP\n\nThe `@alexma03/utcp-file` package provides a straightforward communication protocol for the Universal Tool Calling Protocol (UTCP) client to interact with local files. It's primarily used for loading static UTCP Manuals or OpenAPI specifications directly from local JSON or YAML files, without needing a network request. **Node.js only** - requires file system access.\n\n## Features\n\n*   **File `CallTemplate`**: Defines the configuration for file-based tool definitions (`FileCallTemplate`), specifying the `file_path` to the local manual or spec. Authentication is explicitly `undefined` as file access typically relies on local permissions.\n*   **`FileCommunicationProtocol`**: Implements the `CommunicationProtocol` interface for file-based interactions:\n    *   **Tool Discovery**: Reads and parses local JSON or YAML files. It can directly interpret UTCP Manuals or automatically convert OpenAPI (v2/v3) specifications into UTCP `Tool` definitions (by utilizing the `OpenApiConverter` from `@alexma03/utcp-http`).\n    *   **Tool Execution**: When a tool associated with a `FileCallTemplate` is \"called\", the protocol simply returns the raw content of the configured `file_path` as a string. This is useful for retrieving static data, configuration snippets, or even full documentation embedded as a tool.\n    *   **Stateless**: This protocol does not maintain any persistent connections or external resources, making it very lightweight.\n    *   **Path Resolution**: Resolves relative file paths using the `UtcpClient`'s configured root directory (`_rootPath`), ensuring flexibility in project structure.\n\n## Installation\n\n```bash\nbun add @alexma03/utcp-file @alexma03/utcp-sdk\n\n# Or using npm\nnpm install @alexma03/utcp-file @alexma03/utcp-sdk\n```\n\nNote: `@alexma03/utcp-sdk` is a peer dependency. `@alexma03/utcp-http` and `js-yaml` dependencies are included automatically for OpenAPI conversion and YAML parsing.\n\n## Usage\n\nThe File plugin registers automatically when you import it—no manual registration needed. Simply import from `@alexma03/utcp-file` to enable file system support.\n\n```typescript\n// From your application's entry point\n\nimport { UtcpClient } from '@alexma03/utcp-sdk';\nimport { FileCallTemplateSerializer } from '@alexma03/utcp-file';\nimport * as path from 'path';\nimport * as fs from 'fs/promises'; // For creating dummy files\n\nasync function main() {\n  // Create a dummy UTCP manual file for demonstration\n  const manualContent = {\n    \"utcp_version\": \"1.0.0\",\n    \"manual_version\": \"1.0.0\",\n    \"tools\": [\n      {\n        \"name\": \"read_static_data\",\n        \"description\": \"Reads static data from a local file.\",\n        \"inputs\": {},\n        \"outputs\": { \"type\": \"string\", \"description\": \"The content of the file.\" },\n        \"tags\": [\"file\", \"static\"],\n        \"tool_call_template\": {\n          \"name\": \"static_file_reader\",\n          \"call_template_type\": \"file\",\n          \"file_path\": \"./config/static_data.txt\" // The file path for the tool's content\n        }\n      },\n      {\n        \"name\": \"describe_project\",\n        \"description\": \"Provides a description of the project from a local markdown file.\",\n        \"inputs\": {},\n        \"outputs\": { \"type\": \"string\" },\n        \"tags\": [\"documentation\"],\n        \"tool_call_template\": {\n          \"name\": \"project_readme_reader\",\n          \"call_template_type\": \"file\",\n          \"file_path\": \"./README.md\" // Example: reads the project's README\n        }\n      }\n    ]\n  };\n  const configDirPath = path.resolve(process.cwd(), './config');\n  await fs.mkdir(configDirPath, { recursive: true });\n\n  const dummyManualPath = path.resolve(configDirPath, './my_local_manual.json');\n  await fs.writeFile(dummyManualPath, JSON.stringify(manualContent, null, 2));\n\n  const staticDataPath = path.resolve(configDirPath, './static_data.txt');\n  await fs.writeFile(staticDataPath, 'Hello from UTCP File Plugin static data!');\n\n  // Define a CallTemplate to load the local UTCP manual from the 'config' directory\n  const serializer = new FileCallTemplateSerializer();\n  const fileCallTemplate = serializer.validateDict({\n    name: 'local_manual_loader',\n    call_template_type: 'file',\n    file_path: './config/my_local_manual.json', // Path relative to client's root_path\n  });\n\n  const client = await UtcpClient.create(process.cwd(), {\n    manual_call_templates: [fileCallTemplate] // Register the file manual at client startup\n  });\n\n  console.log('File Plugin active. Searching for tools...');\n\n  // Example: Call 'read_static_data' tool. This will return the content of 'static_data.txt'.\n  try {\n    const staticDataReaderTool = await client.searchTools('read static data');\n    if (staticDataReaderTool.length > 0) {\n      const result = await client.callTool(staticDataReaderTool.name, {});\n      console.log('Result from \"read_static_data\" tool:', result);\n    }\n  } catch (error) {\n    console.error('Error calling \"read_static_data\" tool:', error);\n  }\n\n  // Example: Call 'describe_project' tool. This will return the content of the project's README.md.\n  try {\n    const projectDescTool = await client.searchTools('project description');\n    if (projectDescTool.length > 0) {\n      const result = await client.callTool(projectDescTool.name, {});\n      console.log('Result from \"describe_project\" tool (first 100 chars):', String(result).substring(0, 100) + '...');\n    }\n  } catch (error) {\n    console.error('Error calling \"describe_project\" tool:', error);\n  } finally {\n    // Clean up dummy files\n    await fs.unlink(dummyManualPath);\n    await fs.unlink(staticDataPath);\n    await fs.rmdir(configDirPath); // Remove the config directory\n  }\n\n  await client.close(); // No-op for file protocol, but good practice\n}\n\nmain().catch(console.error);\n```\n\n## Comparison with @alexma03/utcp-text\n\n| Feature | @alexma03/utcp-file | @alexma03/utcp-text |\n|---------|------------|-----------|\n| Browser compatible | ❌ No | ✅ Yes |\n| Node.js compatible | ✅ Yes | ✅ Yes |\n| File system access | ✅ Yes | ❌ No |\n| Direct content | ❌ No | ✅ Yes |\n| Use case | Server-side file reading | Web apps, inline content |\n\n## Development\n\nRefer to the root `README.md` for monorepo development and testing instructions.\n","readmeFilename":"README.md"}