server/SERVER_SPEC.md

ToolStore Server Specification

Status: Planning Focus: Central Registry for Publishing & Distributing Tools

---

1. Core Architecture

The server acts as the "Source of Truth" for the public tool index.

Components

1. API (FastAPI): Handles publishing and index generation.
2. Database (SQLite/Postgres): Stores persistent tool data and user accounts.
3. Storage: Stores raw JSON tool definitions (could be DB or S3).

---

2. API Endpoints

Public

• GET /index.json: Returns the full list of tools (the "Index"). Cached aggressively.
• GET /tools/{name}: Returns details for a specific tool.
• GET /search?q=...: Server-side search (optional, since client does local search).

Publisher (Authenticated)

• POST /auth/register: Create a developer account.
• POST /auth/login: Get an API token.
• POST /tools/publish: Upload a new tool definition (tool.json).
  • Validates schema.
  • Checks namespace ownership.
  • Updates the database.

---

3. Database Schema (SQLModel)

User

• id: int
• username: str (unique)
• email: str
• password_hash: str
• created_at: datetime

Tool

• id: int
• name: str (unique)
• owner_id: int (FK -> User)
• version: str
• type: str ('api', 'mcp')
• description: str
• definition: JSON (The full tool schema)
• created_at: datetime
• updated_at: datetime
• downloads: int

---

4. Implementation Plan

Phase 1: Project Skeleton

• Initialize FastAPI project (server/app).
• Setup SQLModel database connection.
• Create User and Tool models.

Phase 2: Authentication

• Implement User Registration.
• Implement Login (JWT Tokens).
• Protect publish endpoints.

Phase 3: Publishing Flow

• Implement POST /tools/publish.
• Add JSON Schema validation for uploaded tools.
• Ensure unique names.

Phase 4: Index Generation

• Implement GET /index.json.
• Query DB -> Format as massive JSON list.
• Add simple caching headers.

---

Goal: A running server where I can POST a tool JSON and then GET index.json to see it.