@rapidthoughtlabs/heku 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-11
+
+### Added
+- **`heku update`** now updates registry-installed configs to their latest versions (instead of updating the heku binary). Accepts an optional target: `heku update github-http`, `heku update linear:graphql`, or `heku update @ns/linear` (all connector variants). Local credentials (`connector.env`) and overlays are preserved on update.
+- **`one.registry_update`** MCP tool — same update logic callable by an LLM agent. Updates one config by `config_id` or all installed configs when no argument is passed.
+- **`one.list_configs`** now returns `[{ id, name, description }]` objects instead of a flat array of IDs, so agents can identify the right config without an extra round-trip.
+
+### Changed
+- Publish modal always shows the version field. New (unpublished) configs show an empty field with a "not published yet" hint; existing configs are pre-filled with the next patch version and show the current published version as a hint.
+- Flat manifest (`search`, `list_configs`, `list_tools`, `invoke`) no longer prefixes tool descriptions with `[one]` — it was noise when only four tools are shown. Namespaced mode is unchanged.
+- Discovery tool descriptions updated with explicit workflow steps and call examples for users without custom system prompts.
+
 ## [0.2.0] - 2026-06-09
 
 ### Changed
@@ -35,7 +47,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Initial public release on npm as `@rapidthoughtlabs/mcpone`.
 - Single dynamic MCP server that turns JSON configs into working API tools.
 
-[Unreleased]: https://github.com/RapidThoughtLabs/heku/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/RapidThoughtLabs/heku/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/RapidThoughtLabs/heku/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/RapidThoughtLabs/heku/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/RapidThoughtLabs/heku/compare/v0.1.0...v0.1.2
 [0.1.0]: https://github.com/RapidThoughtLabs/heku/releases/tag/v0.1.0

package/README.md

@@ -1,6 +1,6 @@
 # heku
 
-> One server. Any REST API. Any LLM.
+> One server. Any API. Any LLM.
 
 **heku** is a single dynamic [Model Context Protocol](https://modelcontextprotocol.io) server that turns JSON config files into working API tools. No code to write — drop a config, and your LLM gets the tools instantly.
 
@@ -8,13 +8,21 @@ Stop building one MCP server per API. Build one config.
 
 ---
 
+## Try it now
+
+**[console.rapidthoughtlabs.space](https://console.rapidthoughtlabs.space)** — hosted console you can point at any running heku instance. Connect, browse configs, chat with your tools, and inspect the system prompt — no local build needed.
+
+**[app.rapidthoughtlabs.space](https://app.rapidthoughtlabs.space)** — **heku hub**, the online registry for browsing, installing, and publishing heku configs. Find community-built connectors for GitHub, Slack, Linear, and more — or publish your own.
+
+---
+
 ## Features
 
-- **7 connector types** — HTTP, gRPC, GraphQL, CLI, File, child-MCP, and Internal (self-management)
+- **8 connector types** — 4 standard (HTTP, GraphQL, gRPC, child-MCP) + 4 experimental (CLI, File, SQL, MongoDB)
 - **Hot-reload** — add or edit a config, tools update live without restart
 - **Auto-discovery** — gRPC reflection, GraphQL introspection, and child MCP tool listing fill in tools automatically
 - **Built-in console UI** — React dashboard for chat, config editing, and registry browsing
-- **Registry** — publish and install community configs from [mcp.rapidthoughtlabs.space](https://mcp.rapidthoughtlabs.space)
+- **heku hub** — publish and install community configs from [app.rapidthoughtlabs.space](https://app.rapidthoughtlabs.space)
 - **Auth handled** — bearer, basic, API key, and OAuth2 with `.env`-based credential management
 - **Self-managing** — the server can create and edit its own configs via internal tools
 
@@ -39,12 +47,13 @@ heku start
 
 ## Quick start
 
-Create a config in `mcp-configs/mcp.github.json`:
+Create `mcp-configs/mcp.github.json`:
 
 ```json
 {
-  "id": "github",
+  "id": "github-http",
   "name": "GitHub API",
+  "description": "Manage GitHub repos, issues, and pull requests",
   "connector": {
     "type": "http",
     "base_url": "https://api.github.com",
@@ -64,33 +73,327 @@ Create a config in `mcp-configs/mcp.github.json`:
 }
 ```
 
-Set your token:
-
 ```bash
-heku auth setup github
+heku auth setup github-http   # writes GITHUB_TOKEN to .env
+heku start
 ```
 
-Start the server:
+Your LLM now has a `github-http.list_repos` tool.
 
-```bash
-heku start
+---
+
+## Connectors
+
+Tool names follow the pattern `config_id.tool_name` — e.g. `github-http.list_repos`, `linear-graphql.create_issue`.
+
+### Standard
+
+#### `http` — REST API
+
+Define each endpoint as a tool. Supports `path`, `query`, `body`, and `header` params.
+
+```json
+{
+  "id": "stripe-http",
+  "name": "Stripe",
+  "connector": {
+    "type": "http",
+    "base_url": "https://api.stripe.com/v1",
+    "auth": { "type": "bearer", "token_env": "STRIPE_API_KEY" }
+  },
+  "tools": [
+    {
+      "name": "list_customers",
+      "description": "List Stripe customers with optional filters",
+      "method": "GET",
+      "path": "/customers",
+      "params": [
+        { "name": "limit",  "type": "number", "required": false, "location": "query", "description": "Max results (1–100)" },
+        { "name": "email",  "type": "string", "required": false, "location": "query", "description": "Filter by email address" }
+      ]
+    },
+    {
+      "name": "create_customer",
+      "description": "Create a new Stripe customer",
+      "method": "POST",
+      "path": "/customers",
+      "params": [
+        { "name": "email", "type": "string", "required": true,  "location": "body", "description": "Customer email" },
+        { "name": "name",  "type": "string", "required": false, "location": "body", "description": "Full name" }
+      ]
+    }
+  ]
+}
+```
+
+**Tool fields:** `name`, `description`, `method` (`GET`/`POST`/`PUT`/`PATCH`/`DELETE`), `path` (supports `{{param}}` placeholders), `params[]`, `body_template?`, `response_map?`, `error_map?`
+
+**Param locations:** `path` · `query` · `body` · `header`
+
+---
+
+#### `graphql` — GraphQL API
+
+Tools are auto-discovered via introspection. Set `tools: []`.
+
+```json
+{
+  "id": "linear-graphql",
+  "name": "Linear",
+  "connector": {
+    "type": "graphql",
+    "endpoint": "https://api.linear.app/graphql",
+    "auth": { "type": "bearer", "token_env": "LINEAR_API_KEY" },
+    "include_mutations": true,
+    "include_queries": true
+  },
+  "tools": []
+}
+```
+
+**Connector fields:** `endpoint`, `auth?`, `introspect?` (default `true`), `include_mutations?` (default `true`), `include_queries?` (default `true`), `headers?`, `timeout_ms?`
+
+---
+
+#### `grpc` — gRPC service
+
+Tools are auto-discovered via server reflection or a `.proto` file. Set `tools: []`.
+
+```json
+{
+  "id": "myservice-grpc",
+  "name": "My gRPC Service",
+  "connector": {
+    "type": "grpc",
+    "endpoint": "localhost:50051",
+    "reflection": true,
+    "tls": false
+  },
+  "tools": []
+}
+```
+
+Or with a proto file:
+
+```json
+{
+  "connector": {
+    "type": "grpc",
+    "endpoint": "grpc.example.com:443",
+    "proto_path": "./protos/service.proto",
+    "tls": true,
+    "auth": { "type": "bearer", "token_env": "GRPC_TOKEN" }
+  }
+}
+```
+
+**Connector fields:** `endpoint`, `reflection?` or `proto_path?` (one required), `tls?` (`true`/`false` or cert object), `auth?`, `metadata?`, `service_filter?`, `timeout_ms?`
+
+---
+
+#### `mcp` — child MCP server
+
+Spawn any existing MCP server (stdio or SSE) and proxy its tools through heku. Tools are auto-discovered. Set `tools: []`.
+
+```json
+{
+  "id": "filesystem-mcp",
+  "name": "Filesystem MCP",
+  "connector": {
+    "type": "mcp",
+    "transport": "stdio",
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+    "install_command": "npm",
+    "install_args": ["install", "-g", "@modelcontextprotocol/server-filesystem"]
+  },
+  "tools": []
+}
+```
+
+SSE transport:
+
+```json
+{
+  "connector": {
+    "type": "mcp",
+    "transport": "sse",
+    "url": "http://localhost:8080/sse"
+  }
+}
+```
+
+**Connector fields:** `transport` (`stdio`/`sse`), `command?` + `args?` + `env?` (stdio), `url?` (sse), `install_command?`, `install_args?`, `install_cwd?`, `install_env?`, `install_timeout_ms?`, `active?`
+
+> **Note:** `mcp` configs cannot be published to the registry — they reference local processes.
+
+---
+
+### Experimental
+
+> These connector types are functional but their config schema and behaviour may change in future releases.
+
+---
+
+#### `cli` — shell command
+
+Wrap any CLI tool as an MCP tool. Use `args_template` for positional args or `stdin_template` to pipe input.
+
+```json
+{
+  "id": "git-cli",
+  "name": "Git",
+  "connector": { "type": "cli" },
+  "tools": [
+    {
+      "name": "log",
+      "description": "Show recent git commits",
+      "args_template": ["git", "log", "--oneline", "-{{limit}}"],
+      "params": [
+        { "name": "limit", "type": "number", "required": false, "description": "Number of commits to show" }
+      ],
+      "output_as": "text"
+    },
+    {
+      "name": "diff",
+      "description": "Show unstaged changes",
+      "command": "git diff",
+      "params": [],
+      "output_as": "text"
+    }
+  ]
+}
+```
+
+**Tool fields:** `name`, `description`, `params[]`, `command?` (string) or `args_template?` (array), `stdin_template?`, `output_as?` (`"text"` | `"json"`)
+
+---
+
+#### `file` — filesystem
+
+Read, write, append, delete, or list files. `path_template` supports `{{param}}` placeholders.
+
+```json
+{
+  "id": "notes-file",
+  "name": "Notes",
+  "connector": { "type": "file" },
+  "tools": [
+    {
+      "name": "read_note",
+      "description": "Read a note by name",
+      "operation": "read",
+      "path_template": "/home/user/notes/{{name}}.md",
+      "params": [
+        { "name": "name", "type": "string", "required": true, "description": "Note filename without extension" }
+      ]
+    },
+    {
+      "name": "save_note",
+      "description": "Save or overwrite a note",
+      "operation": "write",
+      "path_template": "/home/user/notes/{{name}}.md",
+      "content_template": "{{content}}",
+      "params": [
+        { "name": "name",    "type": "string", "required": true, "description": "Note filename without extension" },
+        { "name": "content", "type": "string", "required": true, "description": "Note content" }
+      ]
+    }
+  ]
+}
+```
+
+**Tool fields:** `name`, `description`, `params[]`, `operation` (`read`/`write`/`append`/`delete`/`list`), `path_template`, `content_template?` (required for `write`/`append`)
+
+---
+
+#### `sql` — relational database
+
+Named SQL queries with `:param` placeholders. Supports PostgreSQL, MySQL, and SQLite.
+
+```json
+{
+  "id": "analytics-sql",
+  "name": "Analytics DB",
+  "connector": {
+    "type": "sql",
+    "dialect": "postgres",
+    "connection_string_env": "DATABASE_URL"
+  },
+  "tools": [
+    {
+      "name": "active_users",
+      "description": "Count active users in a date range",
+      "sql": "SELECT COUNT(*) as count FROM users WHERE created_at BETWEEN :from AND :to AND active = true",
+      "params": [
+        { "name": "from", "type": "string", "required": true, "description": "Start date (ISO 8601)" },
+        { "name": "to",   "type": "string", "required": true, "description": "End date (ISO 8601)" }
+      ],
+      "max_rows": 1
+    }
+  ]
+}
 ```
 
-Your LLM now has a `github.list_repos` tool. That's it.
+**Connector fields:** `dialect` (`postgres`/`mysql`/`sqlite`), `connection_string_env?` or field-based (`host`, `port`, `database`, `username_env`, `password_env`), `ssl?`, `pool_max?`
+
+**Tool fields:** `name`, `description`, `params[]`, `sql` (`:name` placeholders only — no `{{}}`, no `?`, no `$N`), `max_rows?` (1–10000), `timeout_ms?`
 
 ---
 
-## Connector types
+#### `mongodb` — MongoDB
+
+Document operations with JSON templates. Placeholders use `{{param}}` in templates.
+
+```json
+{
+  "id": "catalog-mongo",
+  "name": "Product Catalog",
+  "connector": {
+    "type": "mongodb",
+    "database": "catalog",
+    "connection_string_env": "MONGO_URI"
+  },
+  "tools": [
+    {
+      "name": "find_products",
+      "description": "Search products by category and price range",
+      "collection": "products",
+      "operation": "find",
+      "filter_template": { "category": "{{category}}", "price": { "$lte": "{{max_price}}" } },
+      "params": [
+        { "name": "category",  "type": "string", "required": true,  "description": "Product category" },
+        { "name": "max_price", "type": "number", "required": false, "description": "Maximum price" }
+      ],
+      "max_rows": 50
+    }
+  ]
+}
+```
+
+**Connector fields:** `database`, `connection_string_env?` or `host?`+`port?`, `auth_source?`, `tls?`
+
+**Tool fields:** `name`, `description`, `params[]`, `collection`, `operation` (`find`/`findOne`/`aggregate`/`insertOne`/`insertMany`/`updateOne`/`updateMany`/`deleteOne`/`deleteMany`/`countDocuments`/`distinct`), plus operation-specific templates: `filter_template`, `update_template`, `document_template`, `documents_template`, `pipeline_template`, `projection?`, `sort?`, `max_rows?`, `limit?`, `timeout_ms?`
+
+---
 
-| Type | Use case |
+## Auth types
+
+All credentials read from environment variables — `heku auth setup` writes them to `.env`:
+
+| Type | Header |
 |---|---|
-| `http` | REST APIs — define method, path, params, response mapping |
-| `grpc` | gRPC services — load via `.proto` file or server reflection; tools auto-discovered |
-| `graphql` | GraphQL APIs — introspection-based auto-discovery, or define operations manually |
-| `cli` | Wrap any shell command as a tool with templated args/stdin |
-| `file` | Filesystem operations: read, write, append, delete, list |
-| `mcp` | Spawn another MCP server (stdio or SSE) and proxy its tools through heku |
-| `internal` | heku's own management surface — create configs, install from registry, set auth |
+| `bearer` | `Authorization: Bearer {token}` |
+| `basic` | `Authorization: Basic base64(user:token)` |
+| `api_key` | Custom header, e.g. `X-API-Key` |
+| `oauth2_static` | Pre-acquired OAuth2 access token |
+
+```json
+{ "type": "bearer",       "token_env": "GITHUB_TOKEN" }
+{ "type": "api_key",      "key_env": "MY_KEY", "header_name": "X-Api-Key" }
+{ "type": "basic",        "username_env": "MY_USER", "token_env": "MY_PASS" }
+{ "type": "oauth2_static","token_env": "MY_OAUTH_TOKEN" }
+```
 
 ---
 
@@ -119,43 +422,17 @@ heku update                  Update heku to the latest version
 heku help                    Show usage
 ```
 
-Run with `--http` to start the console UI alongside the stdio server:
+Start with the console UI:
 
 ```bash
 heku start --http --port 3456
 ```
 
----
-
-## Configuration
-
-### Config file shape
-
-Configs live in `mcp-configs/mcp.{id}.json`:
-
-```typescript
-{
-  id: string;                  // becomes the tool namespace prefix
-  name: string;
-  description?: string;        // shown to the LLM
-  connector: ConnectorConfig;  // one of 7 types
-  tools: ToolDef[];            // empty for auto-discovery (grpc/graphql/mcp)
-  overlays?: {                 // override tool descriptions without editing the config
-    [toolName: string]: { description?: string }
-  };
-}
-```
-
-### Auth types
-
-All credentials read from environment variables — `heku auth setup` writes them to `.env`:
+Then open **[console.rapidthoughtlabs.space](https://console.rapidthoughtlabs.space)** and connect to `http://localhost:3456`.
 
-- **`bearer`** — `Authorization: Bearer {token}`
-- **`basic`** — base64(username:token)
-- **`api_key`** — custom header (e.g. `X-API-Key`)
-- **`oauth2_static`** — pre-acquired OAuth2 access token
+---
 
-### System config (optional)
+## System config (optional)
 
 Drop `heku.config.json` in your config directory:
 
@@ -163,7 +440,7 @@ Drop `heku.config.json` in your config directory:
 {
   "log_level": "info",
   "rate_limits": {
-    "github": { "requests_per_minute": 60 }
+    "github-http": { "requests_per_minute": 60 }
   },
   "self_config": true
 }
@@ -173,28 +450,27 @@ Drop `heku.config.json` in your config directory:
 
 ## Console UI
 
-The dashboard is a React + Vite app that talks to the heku server:
+The dashboard is a React + Vite app — available hosted at **[console.rapidthoughtlabs.space](https://console.rapidthoughtlabs.space)** or embedded when you run `heku start --http`.
 
-- **Chat** — test tools through a model of your choice
+- **Chat** — test tools through a model of your choice (OpenAI, Together AI)
 - **Configs** — visual editor for connector and tool definitions
+- **Prompts** — inspect the system prompt layers and token counts
 - **Registry** — browse, install, and publish configs
-- **Auth** — see credential status across all configs at a glance
-
-Built with React 19, TailwindCSS v4, Zustand, and the MCP SDK.
+- **Auth** — credential status across all configs at a glance
 
 ---
 
-## Registry
+## heku hub
 
-[**mcp.rapidthoughtlabs.space**](https://mcp.rapidthoughtlabs.space) is the default registry for sharing configs.
+**[app.rapidthoughtlabs.space](https://app.rapidthoughtlabs.space)** is the default registry for sharing configs — browse community connectors, install with one command, and publish your own.
 
 ```bash
 heku install @rtl/github
 heku install @rtl/slack@1.2.0
-heku publish my-config.json
+heku publish mcp-configs/mcp.stripe-http.json
 ```
 
-Use `--registry` to point at a different one.
+Use `--registry <url>` to point at a self-hosted registry.
 
 ---
 
@@ -227,7 +503,30 @@ mcp-configs/     Local config files (gitignored)
 
 ## Tech stack
 
-TypeScript · Node.js (ESM) · `@modelcontextprotocol/sdk` · Express · React 19 · Vite · TailwindCSS · Zustand · `@grpc/grpc-js` · GraphQL · tsup · Vitest
+TypeScript · Node.js (ESM) · `@modelcontextprotocol/sdk` · Express · React 19 · Vite · Zustand · `@grpc/grpc-js` · GraphQL · tsup · Vitest
+
+---
+
+## Changelog
+
+### 0.3.1
+- Renamed meta-tool namespace from `mcp.one.*` to `heku.*` across all connectors, prompts, and client code
+- Fixed deployed console manifest style switcher (settings API calls now use the correct bridge base URL)
+- Fixed prompt page config catalog not refreshing when heku connects after page load
+- Markdown rendering in the demo chat — assistant responses now render formatted text
+- Config catalog descriptions now show in composed prompt preview; falls back to display name when description is absent
+- Dual manifest preview in Prompts page — flat and namespaced styles with separate token counts
+- heku server version now reads from `package.json` at runtime in dev mode instead of showing `0.0.0-dev`
+
+### 0.3.0
+- Registry versioning overhaul — semver-based publish/install flow
+- CLI registry commands: `install`, `uninstall`, `fork`, `publish`
+- Console registry browser tab
+
+### 0.2.x
+- SQL and MongoDB connector types (experimental)
+- Config write lock — block LLM agents from mutating configs
+- Hot-reload watcher improvements
 
 ---