client/README.md

ToolStore CLI

pip for AI agents — the universal meta-tool client.

---

The ToolStore CLI is the local client that gives any AI agent instant access to every tool in the ecosystem — public APIs, MCP servers, local skills, and sandboxed code modules — all through a single, uniform interface.

It handles discovery, inspection, schema conversion, and execution across all tool types. The agent doesn't need to know whether a tool is an HTTP endpoint, a Docker container, or an MCP server — it just calls it.

For the full vision and architecture, see the main README.

---

🚀 Quick Start

Install

pip install -e .

Pull the public tool index

toolstore update                    # fetch the latest index
toolstore search "weather"          # search across all tool types
toolstore info weather-api          # inspect a tool's schema

Run a tool

toolstore use world-time-api --timezone "America/New_York"

Publish your own tool

toolstore publish my-tool.json

👤 Authentication & Publishing

To publish your own tools to the registry, you need a developer account.

1. Register an Account

Since the CLI is currently optimized for tools, registration is handled via the API directly (or use curl):

curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "myuser",
    "email": "myuser@example.com",
    "password": "mypassword"
  }'

2. Login

Once registered, you can login via the CLI to save your credentials locally:

$ toolstore login
Username: myuser
Password: mypassword
Logging in to http://localhost:8000...
Login successful!

(Tokens are saved to ~/.toolstore/credentials)

3. Publish a Tool

Create a tool.json file (see below) and run:

$ toolstore publish tool.json

🛠️ Creating Tools (The Standard)

ToolStore uses a simple JSON format to define tools.

1. API Tool Standard (V1)

To add a public API or local service, create a definition file (e.g., my-tool.json):

{
  "name": "weather-api",
  "version": "1.0.0",
  "type": "api",
  "description": "Get current weather for any city",
  "author": "username",
  "license": "MIT",
  
  "endpoint": "https://api.open-meteo.com/v1/forecast",
  "method": "GET",
  
  "auth": {
    "type": "none"  // V1 only supports auth-free APIs
  },
  
  "schema": {
    "input": {
      "latitude": { "type": "number", "required": true, "description": "Latitude" },
      "longitude": { "type": "number", "required": true, "description": "Longitude" }
    },
    "output": {
      "temperature": "number",
      "unit": "string"
    }
  },
  
  "examples": [
    {
      "input": { "latitude": 37.77, "longitude": -122.41 },
      "output": { "temperature": 18, "unit": "celsius" }
    }
  ]
}

📖 Documentation

• V1_SPEC.md - The technical specification for this implementation.
• future_planning/ - Original research and long-term roadmap.

🛠️ Development status

Current Phase: V1 Implementation (Foundation)