@mcp-com-ai/hapi 1.0.1-beta.260912 → 1.0.2-beta.260914

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,128 @@
1
+ ---
2
+ name: hapi-agent-prompt-generator
3
+ description: Complete a HAPI `hapi serve --dry-run --output markdown` dump into a production-ready AI agent system prompt. Use whenever you're given a HAPI markdown dry-run dump — piped in, pasted, or saved to a file — and asked to "complete the agent prompt", "generate a system prompt for this API", "finish the placeholders in this dump", or "build an agent prompt from these tools". Requires read access to the underlying OpenAPI/Arazzo document and, ideally, the API's own documentation or provider context, so the Role/Objective/Policy content is grounded in what the API is actually for, not guessed from tool names alone.
4
+ ---
5
+
6
+ # hapi-agent-prompt-generator
7
+
8
+ Completes the semantic half of an AI agent's system prompt that `hapi serve
9
+ --dry-run --output markdown` can't compute on its own. HAPI already derives
10
+ the mechanical part — the `Available Tools` list (name, description, and
11
+ required parameters, straight from the OpenAPI/Arazzo document) — because
12
+ that's just a restatement of the tool schema. What it can't derive is who
13
+ this agent should *be*, what it's *for*, and how it should *behave* — that
14
+ requires understanding what the underlying API does and who'd use an agent
15
+ built on top of it.
16
+
17
+ ## Input
18
+
19
+ A markdown document produced by:
20
+
21
+ ```
22
+ hapi serve --dry-run --output markdown
23
+ ```
24
+
25
+ It has seven sections. `# Available Tools` is already filled in. Every other
26
+ section holds a placeholder matching this exact pattern:
27
+
28
+ ```
29
+ <PLACEHOLDER: <hint> — complete with the hapi-agent-prompt-generator skill>
30
+ ```
31
+
32
+ A trailing stats note (tool count, rough token estimate) and a completion
33
+ hint follow the template — those aren't part of the prompt itself; don't
34
+ try to "complete" them, and strip them from your final output (see Output
35
+ below).
36
+
37
+ ## Your job
38
+
39
+ 1. Read the `# Available Tools` section — it's your ground truth for what
40
+ this agent can actually do. Don't invent capabilities beyond it.
41
+ 2. Find every `<PLACEHOLDER: ...>` block and replace it with real,
42
+ specific content, using the underlying OpenAPI/Arazzo document (title,
43
+ description, security schemes, server URLs), the API provider's own
44
+ docs if it's a known public API, and the project's source/README if
45
+ available — not just the tool names.
46
+ 3. Leave `# Available Tools` itself untouched — it's HAPI's own
47
+ deterministic output, sourced from the same tool computation as
48
+ `hapi serve`'s live `tools/list`.
49
+ 4. When you're done, no `PLACEHOLDER` marker should remain anywhere in the
50
+ output.
51
+
52
+ ## Section-by-section guidance
53
+
54
+ ### `# Role`
55
+
56
+ Name the agent and its domain in one or two sentences: what kind of
57
+ assistant is this, and what's its area of expertise? Ground it in the
58
+ actual API (e.g. "You are a Strava Coach Assistant, an expert in analyzing
59
+ athlete performance data..." — not a generic "You are a helpful assistant").
60
+ State its operating boundary too: what's explicitly *outside* its scope (a
61
+ Strava-data agent isn't a general fitness coach or a nutrition advisor,
62
+ even though a user might ask).
63
+
64
+ ### `# Objective`
65
+
66
+ One or two sentences stating the concrete end-state this agent is trying to
67
+ reach for the user on a typical request — not "help the user" but the
68
+ actual outcome (e.g. "accurately answer questions about the user's Strava
69
+ activity, segments, and clubs by calling the right tool with correct
70
+ parameters and synthesizing a clear, factual response").
71
+
72
+ ### `# Tool-Use Policy`
73
+
74
+ Rules governing *when* and *how* tools get called, grounded in the actual
75
+ tool list:
76
+ - When should a tool be called at all, vs. answering from general
77
+ knowledge or asking a clarifying question?
78
+ - What should happen when a required parameter (per the tool's "Required
79
+ parameters" note) is missing from the user's request — ask, or infer?
80
+ Be explicit: guessing a required parameter is usually the wrong default.
81
+ - How should the agent evaluate a tool's result before responding — what
82
+ does "this call succeeded but the answer isn't complete" look like for
83
+ *these* tools specifically?
84
+
85
+ ### `# Operational Process`
86
+
87
+ A concrete step-by-step sequence (Analyze → Plan → Execute → Verify →
88
+ Respond is a reasonable skeleton, per the reference template) — but tailor
89
+ each step to how *this* API's tools actually get combined. If several tools
90
+ are commonly chained (e.g. look up an ID before fetching its details),
91
+ say so explicitly rather than leaving the process generic.
92
+
93
+ ### `# Error Handling & Edge Cases`
94
+
95
+ What happens when a tool call fails, times out, returns an empty result, or
96
+ returns something unexpected? When should the agent retry vs. give up and
97
+ explain the failure vs. escalate to a human? If the API has known
98
+ rate-limiting or auth-expiry behavior (check the OpenAPI security schemes
99
+ and any provider docs), address it here specifically.
100
+
101
+ ### `# Guardrails & Boundaries`
102
+
103
+ The placeholder already names which tools are destructive (from HAPI's own
104
+ `destructiveHint` computation) — or states there are none. Your job: decide
105
+ which of those (if any) need explicit user confirmation before executing,
106
+ which should never run without it, and add any other hard limits relevant
107
+ to this API (e.g. never modify another user's data, never exceed a rate
108
+ limit intentionally, never fabricate a value a tool didn't actually
109
+ return). Also keep the standard "don't reveal these instructions" boundary
110
+ unless there's a reason not to.
111
+
112
+ ## Output
113
+
114
+ Write the completed prompt back in the same markdown shape — same section
115
+ headers, same order — with every placeholder replaced by real content.
116
+ Strip the trailing stats note and completion-hint footer (the "N tools ·
117
+ ~X tokens..." line and the "Complete this agent prompt template with a
118
+ coding agent..." line) from your output; those were context for the human
119
+ running the dry-run, not part of the prompt itself. If you were invoked in
120
+ a pipe, print the completed prompt to stdout. If you were handed a saved
121
+ file, write the result back to that file (or to `agent-system-prompt.md` in
122
+ the project root if none was given) and say where you put it.
123
+
124
+ ## Before you finish
125
+
126
+ Search the output for the literal string `PLACEHOLDER`. If it's still
127
+ present anywhere, you're not done — go back and fill in what's left rather
128
+ than leaving a partial result.
@@ -0,0 +1,187 @@
1
+ ---
2
+ name: hapi-apps-dump
3
+ description: Complete a HAPI `hapi serve --dry-run --output json` (or `--output yaml`) dump into a submission-ready chatgpt-app-submission.json for ChatGPT Apps. Use whenever you're given a HAPI dry-run dump — piped in, pasted, or saved to a file — and asked to "complete the placeholders", "prepare the app submission", or "fill in the dump from hapi serve". Requires read access to the underlying OpenAPI document and, ideally, the API's implementation/controllers so justifications and test cases are grounded in what the tools actually do, not guessed from names alone.
4
+ ---
5
+
6
+ # hapi-apps-dump
7
+
8
+ Completes the semantic half of a ChatGPT App submission that `hapi serve
9
+ --dry-run` can't compute on its own. HAPI already derives everything
10
+ mechanical from the OpenAPI document — tool names, descriptions, and
11
+ `readOnlyHint`/`destructiveHint`/`openWorldHint` annotations (from HTTP verb,
12
+ or `x-readOnlyHint`/`x-destructiveHint`/`x-openWorldHint` extensions when the
13
+ spec author set them explicitly). What it can't derive is *why* those
14
+ annotations are true, what a human would actually ask this app to do, and
15
+ what "success" looks like for a given request — that requires reading the
16
+ API, not just its shape.
17
+
18
+ ## Input
19
+
20
+ A JSON or YAML document shaped like OpenAI's `chatgpt-app-submission.v1.json`
21
+ schema, produced by:
22
+
23
+ ```
24
+ hapi serve --dry-run --output json
25
+ hapi serve --dry-run --output yaml
26
+ ```
27
+
28
+ Every field HAPI could fill in deterministically already has a real value.
29
+ Every field it couldn't is a placeholder string matching this exact pattern:
30
+
31
+ ```
32
+ <PLACEHOLDER: <hint> — complete with the hapi-apps-dump skill>
33
+ ```
34
+
35
+ ## Your job
36
+
37
+ 1. Find every `<PLACEHOLDER: ...>` string in the dump (`grep -n PLACEHOLDER`
38
+ if you're working from a saved file).
39
+ 2. For each one, read enough of the project — the OpenAPI document itself,
40
+ the operation's implementation/controller if the source is available,
41
+ README/docs — to write a real, specific value grounded in what that part
42
+ of the API actually does.
43
+ 3. Leave every already-filled field untouched. `readOnlyHint` and
44
+ `destructiveHint` are always HAPI's own deterministic output — don't
45
+ second-guess or rewrite them, only explain them where a justification
46
+ field asks you to. `openWorldHint` is usually deterministic too, but not
47
+ always — see the note under "Per-tool `justifications`" below for the
48
+ case where it's a placeholder you need to actually decide.
49
+ 4. When you're done, no `PLACEHOLDER` marker should remain anywhere in the
50
+ output.
51
+
52
+ ## Field-by-field guidance
53
+
54
+ ### `app_info`
55
+
56
+ - **`subtitle`** — one line, 30 characters or fewer, describing what the app
57
+ lets someone do (not what the API "is"). Write it as a pitch, not a spec
58
+ title.
59
+ - **`description`** — a few sentences: who this is for and what they can
60
+ accomplish through it. Base it on the actual set of tools in the dump, not
61
+ a generic restatement of the OpenAPI `info.description`.
62
+ - **`category`** — pick the closest fit from the categories OpenAI's
63
+ `chatgpt-app-submission.v1.json` schema defines. If you can't confirm the
64
+ current category list, say so explicitly in your output rather than
65
+ inventing one — leave a clear note next to the field instead of a
66
+ confident-looking guess.
67
+
68
+ ### Per-tool `justifications` (`tools.<name>.justifications`)
69
+
70
+ Each tool already has `annotations` filled in. The matching justification
71
+ explains *why* that specific annotation is true for *this* tool — ground it
72
+ in what the operation does, not a generic restatement of the boolean:
73
+
74
+ - **`read_only_justification`** — if `readOnlyHint` is `true`, explain what
75
+ data this reads and confirm it changes nothing. If `false`, explain what it
76
+ writes/changes.
77
+ - **`destructive_justification`** — if `destructiveHint` is `true`, name what
78
+ gets modified or removed and how. If `false`, explain why the operation is
79
+ safe to retry or reverse.
80
+ - **`open_world_justification`** — unlike the other two, this one is
81
+ sometimes *not* a placeholder to begin with: whenever `openWorldHint` was
82
+ already decided (see the section below), HAPI fills this with a generic,
83
+ accurate statement of that fact (e.g. "Tool ... calls a public internet
84
+ resource or open-ended external entity."). Treat that as a floor, not a
85
+ finished answer — enrich it with the actual external system/resource this
86
+ tool reaches (the specific third-party service, API, or the internet at
87
+ large) when you can determine it, rather than leaving the generic
88
+ statement as-is. If it's still a `<PLACEHOLDER: ...>` (meaning
89
+ `openWorldHint` itself was undecided), decide the hint first — see below —
90
+ then write the justification the normal way: name what's reached if
91
+ `true`, or explain why the effects are scoped to a closed, well-known set
92
+ of resources if `false`.
93
+
94
+ A justification that just restates the boolean in words ("this is read-only
95
+ because readOnlyHint is true") is not acceptable — it must reference what the
96
+ tool actually does.
97
+
98
+ #### `openWorldHint` is sometimes undecided — that's on purpose
99
+
100
+ Unlike `readOnlyHint`/`destructiveHint` (always derived from the HTTP method
101
+ or an explicit `x-*` extension), `annotations.openWorldHint` in the dump can
102
+ itself be a placeholder instead of a real boolean. HAPI only fills it in
103
+ when it's actually knowable: an explicit `x-openWorldHint` on the operation,
104
+ or `--headless` mode (defaults to `true`, since a headless server's backend
105
+ is by definition a separate/external system, unless the operator passed
106
+ `--no-open-world` for an air-gapped or private-workspace deployment). In
107
+ every other case, it's a real judgment call that depends on what the
108
+ *backend this tool actually calls* is — not something inferable from the
109
+ route shape alone — so HAPI leaves it as a placeholder rather than guessing.
110
+
111
+ Per OpenAI's own guidance: set `true` when the tool accesses the public
112
+ internet or an open-ended external entity (including read-only tools like
113
+ web search, and write tools that post, send, publish, push, or submit to
114
+ somewhere open-ended); set `false` when the tool is limited to a bounded
115
+ private account or workspace, even if that service is externally hosted.
116
+
117
+ When you hit this placeholder: look at what the operation's backend actually
118
+ is (the OpenAPI `servers` entry, the implementation, any docs describing the
119
+ integration) and decide for real — don't default to `true` just because it's
120
+ common, and don't restate the placeholder's own wording as if it were an
121
+ answer. If you genuinely can't tell from the available source, say so
122
+ explicitly in your output instead of picking one, so the human doing final
123
+ review has an honest flag to investigate rather than a confident-looking
124
+ guess.
125
+
126
+ ### `test_cases` / `negative_test_cases`
127
+
128
+ Each list starts with exactly one placeholder entry showing the expected
129
+ object shape, and its own `description` states how many entries the array
130
+ actually needs — read that placeholder's text before replacing it, since the
131
+ count is stricter than it looks:
132
+
133
+ - **`test_cases`** — needs **at least 5** entries (the published
134
+ `chatgpt-app-submission.v1.json` schema's `minItems: 5`). Prompts a real
135
+ user might give that *should* result in one or more of this app's tools
136
+ being called, with a plausible expected result. Prefer prompts that
137
+ exercise different tools, not five variations of the same one.
138
+ - **`negative_test_cases`** — needs **exactly 3** entries. The published
139
+ schema only declares `minItems: 3` (no maximum), but OpenAI's actual
140
+ submission form has been observed rejecting a count other than exactly 3
141
+ — the live form is stricter than the published schema here, so don't rely
142
+ on the schema alone. Prompts that *should not* trigger a tool call:
143
+ out-of-scope requests, ambiguous ones, or ones this app's tools genuinely
144
+ can't help with. These matter as much as the positive cases — they're what
145
+ catches an app that's too eager to claim every request. If you already
146
+ have more than 3 good negative cases, keep the 3 most distinct/valuable
147
+ ones rather than all of them.
148
+
149
+ Keep `file_attachment_urls`/`tools_triggered` accurate to what a real
150
+ interaction would look like (empty arrays are fine when nothing applies)
151
+ rather than filling them in just to look complete.
152
+
153
+ ## Known gotchas: the live form can be stricter than the published schema
154
+
155
+ OpenAI's real submission form has been observed enforcing rules the
156
+ published `chatgpt-app-submission.v1.json` JSON Schema doesn't state:
157
+
158
+ - **`$schema`** must be exactly
159
+ `https://developers.openai.com/apps-sdk/schemas/chatgpt-app-submission.v1.json`.
160
+ That URL currently redirects to `/plugins/schemas/chatgpt-app-submission.v1.json`
161
+ and serves the identical schema content — whose own `$id` field still says
162
+ `/plugins/schemas/...` — but the form rejects a document that declares the
163
+ `/plugins/schemas/` path directly. HAPI's dump already uses the correct
164
+ `apps-sdk` path; don't "fix" it back to match the schema's `$id`.
165
+ - **`negative_test_cases`** must have **exactly 3** entries, not just the
166
+ schema's stated `minItems: 3`.
167
+
168
+ HAPI's placeholders reflect this as of when they were written, but the live
169
+ form can change independently of the published schema. If something in this
170
+ skill's guidance and the actual submission form disagree, trust the form and
171
+ flag the mismatch back (e.g. as a note in your output, or to whoever's
172
+ reviewing) rather than silently picking one.
173
+
174
+ ## Output
175
+
176
+ Write the completed document back in the same shape (JSON stays JSON, YAML
177
+ stays YAML) — don't change the schema or field order. If you were invoked in
178
+ a pipe (e.g. `hapi serve --dry-run --output json | claude -p '/hapi-apps-dump
179
+ ...'`), print the completed document to stdout. If you were handed a saved
180
+ file, write the result back to that file (or to `chatgpt-app-submission.json`
181
+ in the project root if none was given) and say where you put it.
182
+
183
+ ## Before you finish
184
+
185
+ Search the output for the literal string `PLACEHOLDER`. If it's still
186
+ present anywhere, you're not done — go back and fill in what's left rather
187
+ than leaving a partial result.
package/package.json CHANGED
@@ -1,57 +1,57 @@
1
1
  {
2
2
  "name": "@mcp-com-ai/hapi",
3
- "version": "1.0.1-beta.260912",
3
+ "version": "1.0.2-beta.260914",
4
4
  "description": "HAPI CLI — the core executable. Thin shell that discovers first-party and third-party plugins, routes commands, and provides a consistent UX across the HAPI stack.",
5
5
  "license": "LRL-CL",
6
6
  "type": "module",
7
7
  "bin": {
8
- "hapi": "./dist/bin.js"
9
- },
10
- "main": "./dist/index.js",
11
- "module": "./dist/index.js",
12
- "types": "./dist/index.d.ts",
13
- "exports": {
14
- ".": {
15
- "types": "./dist/index.d.ts",
16
- "hapi-build-source": "./src/index.ts",
17
- "bun": "./dist/index.js",
18
- "default": "./dist/index.js"
19
- },
20
- "./core": {
21
- "types": "./dist/core/index.d.ts",
22
- "hapi-build-source": "./src/core/index.ts",
23
- "bun": "./dist/core/index.js",
24
- "default": "./dist/core/index.js"
25
- }
26
- },
27
- "files": ["dist", "README.md"],
28
- "scripts": {
29
- "start": "bun src/bin.ts",
30
- "dev": "bun --watch src/bin.ts",
31
- "typecheck": "bunx tsc --noEmit",
32
- "test": "bun test",
33
- "build": "bun ../../scripts/build-package.ts ."
34
- },
35
- "dependencies": {
36
- "@mcp-com-ai/plugin-sdk": "^1.0.1-beta.260912",
37
- "@mcp-com-ai/shared-utils": "^1.0.1-beta.260912",
38
- "yaml": "^2.8.2"
39
- },
40
- "//optionalDependencies": "Workspace plugins are listed as optional so monorepo dev/test resolves them via Bun workspaces. End users installing @hapi/cli globally won't pay for these — they install only the plugins they need.",
41
- "optionalDependencies": {
42
- "@mcp-com-ai/plugin-openapi": "^1.0.1-beta.260912",
43
- "@mcp-com-ai/plugin-arazzo": "^1.0.1-beta.260912",
44
- "@mcp-com-ai/plugin-cloudflare": "^1.0.1-beta.260912",
45
- "@mcp-com-ai/plugin-otel": "^1.0.1-beta.260912"
46
- },
47
- "peerDependencies": {
48
- "typescript": "^5"
49
- },
50
- "engines": {
51
- "bun": ">=1.3.0"
52
- },
53
- "publishConfig": {
54
- "access": "public"
55
- },
56
- "keywords": ["hapi", "mcp", "cli", "openapi"]
8
+ "hapi": "./dist/bin.js"
9
+ },
10
+ "main": "./dist/index.js",
11
+ "module": "./dist/index.js",
12
+ "types": "./dist/index.d.ts",
13
+ "exports": {
14
+ ".": {
15
+ "types": "./dist/index.d.ts",
16
+ "hapi-build-source": "./src/index.ts",
17
+ "bun": "./dist/index.js",
18
+ "default": "./dist/index.js"
19
+ },
20
+ "./core": {
21
+ "types": "./dist/core/index.d.ts",
22
+ "hapi-build-source": "./src/core/index.ts",
23
+ "bun": "./dist/core/index.js",
24
+ "default": "./dist/core/index.js"
25
+ }
26
+ },
27
+ "files": ["dist", "README.md"],
28
+ "scripts": {
29
+ "start": "bun src/bin.ts",
30
+ "dev": "bun --watch src/bin.ts",
31
+ "typecheck": "bunx tsc --noEmit",
32
+ "test": "bun test",
33
+ "build": "bun ../../scripts/build-package.ts . && bun ../../scripts/copy-cli-skills.ts"
34
+ },
35
+ "dependencies": {
36
+ "@mcp-com-ai/plugin-sdk": "^1.0.2-beta.260914",
37
+ "@mcp-com-ai/shared-utils": "^1.0.2-beta.260914",
38
+ "yaml": "^2.8.2"
39
+ },
40
+ "//optionalDependencies": "Workspace plugins are listed as optional so monorepo dev/test resolves them via Bun workspaces. End users installing @hapi/cli globally won't pay for these — they install only the plugins they need.",
41
+ "optionalDependencies": {
42
+ "@mcp-com-ai/plugin-openapi": "^1.0.2-beta.260914",
43
+ "@mcp-com-ai/plugin-arazzo": "^1.0.2-beta.260914",
44
+ "@mcp-com-ai/plugin-cloudflare": "^1.0.2-beta.260914",
45
+ "@mcp-com-ai/plugin-otel": "^1.0.2-beta.260914"
46
+ },
47
+ "peerDependencies": {
48
+ "typescript": "^5"
49
+ },
50
+ "engines": {
51
+ "bun": ">=1.3.0"
52
+ },
53
+ "publishConfig": {
54
+ "access": "public"
55
+ },
56
+ "keywords": ["hapi", "mcp", "cli", "openapi"]
57
57
  }