{"id":37836491,"url":"https://github.com/dirmacs/thulp","last_synced_at":"2026-02-01T08:01:30.105Z","repository":{"id":332674169,"uuid":"1134588598","full_name":"dirmacs/thulp","owner":"dirmacs","description":"Execution Context Engineering Platform for AI Agents","archived":false,"fork":false,"pushed_at":"2026-01-15T20:10:07.000Z","size":397,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-18T16:40:59.408Z","etag":null,"topics":["ai","ai-agents","cli","context-engineering","crate","library","llm","rust","thulp"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dirmacs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-14T23:26:36.000Z","updated_at":"2026-01-15T20:09:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dirmacs/thulp","commit_stats":null,"previous_names":["dirmacs/thulp"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/dirmacs/thulp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirmacs%2Fthulp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirmacs%2Fthulp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirmacs%2Fthulp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirmacs%2Fthulp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dirmacs","download_url":"https://codeload.github.com/dirmacs/thulp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dirmacs%2Fthulp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28973038,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T06:46:42.625Z","status":"ssl_error","status_checked_at":"2026-02-01T06:44:56.173Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","cli","context-engineering","crate","library","llm","rust","thulp"],"created_at":"2026-01-16T15:54:27.328Z","updated_at":"2026-02-01T08:01:30.099Z","avatar_url":"https://github.com/dirmacs.png","language":"Rust","readme":"# thulp\n\n[![CI](https://github.com/dirmacs/thulp/actions/workflows/ci.yml/badge.svg)](https://github.com/dirmacs/thulp/actions/workflows/ci.yml)\n[![crates.io](https://img.shields.io/crates/v/thulp-core.svg)](https://crates.io/crates/thulp-core)\n[![docs.rs](https://docs.rs/thulp-core/badge.svg)](https://docs.rs/thulp-core)\n[![License](https://img.shields.io/crates/l/thulp-core.svg)](LICENSE-MIT)\n\n## Execution Context Engineering Platform for AI Agents\n\nThulp is a Rust-based toolkit for building AI agents with rich execution\ncontexts. It provides abstractions for tool discovery, execution, workspace\nmanagement, and integration with the Model Context Protocol (MCP) via the\n[UTCP](https://github.com/universal-tool-calling-protocol/rs-utcp)\n(Universal Tool Calling Protocol) implementation.\n\n## Overview\n\nThulp enables AI agents to interact with external tools and services through a\nunified interface. It handles the complexity of tool discovery, validation,\nexecution, and result handling while providing extensibility through adapters\nand custom integrations.\n\n### Key Features\n\n- **Unified Tool Abstraction**: Consistent interface for defining, validating,\n  and executing tools\n- **MCP Integration**: Full Model Context Protocol support via `rs-utcp` UTCP\n  implementation (tools, resources, prompts)\n- **Type-Safe Parameters**: Strongly-typed parameter validation with JSON\n  Schema support\n- **Query DSL**: Powerful query language for filtering and searching tools\n- **Skill Workflows**: Compose multi-step tool workflows with variable interpolation\n- **SkillExecutor Trait**: Pluggable execution strategies with timeout/retry support\n- **Execution Hooks**: Lifecycle callbacks for observability (before/after skill/step, on_error, on_retry, on_timeout)\n- **Session Management**: Persistent sessions with turn counting, configurable limits, and file-based storage\n- **SKILL.md Parsing**: Load skills from markdown files with YAML frontmatter and scope-based priority\n- **Async by Design**: Built on `tokio` for efficient async execution\n- **CLI with Shell Completions**: Full-featured CLI with JSON output and completions\n- **Browser Automation**: Web fetching and optional CDP support\n- **Comprehensive Testing**: 183 tests with edge-case coverage\n\n## Architecture\n\nThulp is organized as a Cargo workspace with 11 crates:\n\n### Core Crates\n\n| Crate              | Description                                       |\n| ------------------ | ------------------------------------------------- |\n| **thulp-core**     | Core types and traits (`ToolDefinition`, etc.)    |\n| **thulp-mcp**      | MCP transport (STDIO/HTTP, tools, resources)      |\n| **thulp-adapter**  | OpenAPI v2/v3 to tool definition conversion       |\n| **thulp-registry** | Async thread-safe tool registry with tagging      |\n\n### Feature Crates\n\n| Crate                | Description                                       |\n| -------------------- | ------------------------------------------------- |\n| **thulp-query**      | Query DSL for searching and filtering tools       |\n| **thulp-skills**     | Multi-step workflow composition and execution     |\n| **thulp-skill-files**| SKILL.md file parsing with YAML frontmatter       |\n| **thulp-workspace**  | Workspace, session management, and persistence    |\n| **thulp-browser**    | Web fetching, HTML parsing, optional CDP support  |\n| **thulp-guidance**   | Template rendering and LLM guidance primitives    |\n\n### CLI\n\n| Crate         | Description                                        |\n| ------------- | -------------------------------------------------- |\n| **thulp-cli** | CLI with JSON output and shell completions         |\n\n## Installation\n\n### Install CLI\n\n```bash\ncargo install thulp-cli\n```\n\n### Add as Dependency\n\n```toml\n[dependencies]\nthulp-core = \"0.2\"\nthulp-mcp = \"0.2\"\nthulp-query = \"0.2\"\n```\n\nFor MCP with Ares server support:\n\n```toml\n[dependencies]\nthulp-mcp = { version = \"0.2\", features = [\"ares\"] }\n```\n\n## Quick Start\n\n### Defining a Tool\n\n```rust\nuse thulp_core::{ToolDefinition, Parameter, ParameterType};\n\nlet tool = ToolDefinition::builder(\"search\")\n    .description(\"Search for information\")\n    .parameter(\n        Parameter::builder(\"query\")\n            .description(\"Search query\")\n            .param_type(ParameterType::String)\n            .required(true)\n            .build()\n    )\n    .build();\n```\n\n### Connecting to an MCP Server\n\n```rust\nuse thulp_mcp::McpClient;\n\n// Connect via HTTP\nlet client = McpClient::connect_http(\"server\", \"http://localhost:8080\".to_string()).await?;\n\n// Or via STDIO\nlet client = McpClient::connect_stdio(\n    \"server\",\n    \"path/to/mcp-server\".to_string(),\n    None\n).await?;\n\n// List available tools\nlet tools = client.list_tools().await?;\n\n// Execute a tool\nlet result = client.call(\u0026ToolCall::builder(\"tool_name\")\n    .arg_str(\"param\", \"value\")\n    .build()).await?;\n```\n\n### Query DSL\n\n```rust\nuse thulp_query::{parse_query, QueryBuilder};\n\n// Parse natural language query\nlet criteria = parse_query(\"name:search and min:2\")?;\nlet matches: Vec\u003c_\u003e = tools.iter().filter(|t| criteria.matches(t)).collect();\n\n// Or use the builder\nlet query = QueryBuilder::new()\n    .name(\"file\")\n    .min_parameters(1)\n    .build();\nlet results = query.execute(\u0026tools);\n```\n\n### Skill Workflows\n\n```rust\nuse thulp_skills::{Skill, SkillStep};\n\nlet skill = Skill::new(\"search_and_summarize\", \"Search and summarize results\")\n    .with_input(\"query\")\n    .with_step(SkillStep {\n        name: \"search\".to_string(),\n        tool: \"web_search\".to_string(),\n        arguments: json!({\"query\": \"{{query}}\"}),\n        continue_on_error: false,\n    })\n    .with_step(SkillStep {\n        name: \"summarize\".to_string(),\n        tool: \"summarize\".to_string(),\n        arguments: json!({\"text\": \"{{search.results}}\"}),\n        continue_on_error: false,\n    });\n```\n\n## CLI Usage\n\n```bash\n# List tools\nthulp tools list\nthulp tools list --output json\n\n# Show tool details\nthulp tools show \u003ctool-name\u003e\n\n# Validate tool arguments\nthulp tools validate \u003ctool-name\u003e --args '{\"param\": \"value\"}'\n\n# Convert OpenAPI spec to tools\nthulp convert openapi spec.yaml --output tools.yaml\n\n# Run demo\nthulp demo\n\n# Generate shell completions\nthulp completions bash \u003e ~/.local/share/bash-completion/completions/thulp\nthulp completions powershell \u003e\u003e $PROFILE\n```\n\n## Examples\n\nThulp includes 6 comprehensive examples:\n\n```bash\n# Core tool types\ncargo run --example tool_definition\n\n# OpenAPI conversion\ncargo run --example adapter\n\n# MCP integration\ncargo run --example mcp --features mcp\n\n# Query DSL\ncargo run --example query\n\n# Skill workflows\ncargo run --example skills\n\n# Async registry\ncargo run --example registry\n```\n\n## Development\n\n### Building\n\n```bash\n# Build all crates\ncargo build --workspace\n\n# Build with CDP feature\ncargo build -p thulp-browser --features cdp\n\n# Build in release mode\ncargo build --workspace --release\n```\n\n### Testing\n\n```bash\n# Run all tests (183 tests)\ncargo test --workspace\n\n# Run with verbose output\ncargo test --workspace -- --nocapture\n```\n\n### Benchmarking\n\n```bash\ncargo bench -p thulp-core --bench tool_benchmarks\n```\n\n### Code Quality\n\n```bash\ncargo clippy --workspace -- -D warnings\ncargo fmt --all -- --check\n```\n\n## Project Status\n\n**Version**: 0.2.0\n\n### Complete Features\n\n- Core tool abstraction and validation\n- MCP transport (STDIO and HTTP) with tools, resources, prompts\n- Parameter type system with JSON Schema support\n- Query DSL with wildcards and boolean operators\n- Skill workflows with variable interpolation\n- SkillExecutor trait with pluggable execution strategies\n- DefaultSkillExecutor with timeout and retry support\n- ExecutionHooks for lifecycle callbacks and observability\n- Session management with turn counting and persistence\n- SessionManager for file-based session storage\n- SKILL.md file parsing with YAML frontmatter (thulp-skill-files)\n- SkillLoader with scope-based priority (Global/Workspace/Project)\n- OpenAPI v2/v3 conversion (JSON and YAML)\n- CLI with JSON output and shell completions\n- Async thread-safe tool registry with tagging\n- Browser web fetching and HTML parsing\n- 183 tests with comprehensive coverage\n\n### Feature Flags\n\n| Crate          | Flag   | Description                       |\n| -------------- | ------ | --------------------------------- |\n| thulp-mcp      | `ares` | Ares server integration           |\n| thulp-browser  | `cdp`  | Chrome DevTools Protocol support  |\n| thulp-examples | `mcp`  | MCP example                       |\n\n## Contributing\n\nContributions are welcome! Please follow these guidelines:\n\n1. Fork the repository\n2. Create a feature branch\n3. Write tests for new functionality\n4. Ensure all tests pass: `cargo test --workspace`\n5. Run clippy: `cargo clippy --workspace -- -D warnings`\n6. Format code: `cargo fmt --all`\n7. Submit a pull request\n\n## License\n\nLicensed under either of:\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e)\n- MIT license ([LICENSE-MIT](LICENSE-MIT) or \u003chttp://opensource.org/licenses/MIT\u003e)\n\nat your option.\n\n## Links\n\n- [Repository](https://github.com/dirmacs/thulp)\n- [Crates.io](https://crates.io/search?q=thulp)\n- [Documentation](https://docs.rs/thulp-core)\n- [MCP Specification](https://modelcontextprotocol.io/)\n- [rs-utcp](https://github.com/universal-tool-calling-protocol/rs-utcp)\n\n## Acknowledgments\n\n- **rs-utcp**: UTCP protocol implementation (includes MCP transport)\n- **Anthropic**: Model Context Protocol specification\n- **UTCP**: Universal Tool Calling Protocol\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdirmacs%2Fthulp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdirmacs%2Fthulp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdirmacs%2Fthulp/lists"}