mcpill 1.1.0

package/.flowdeck/_energy/OPEN-QUESTIONS.md.template

@@ -0,0 +1,109 @@
+---
+title: "Open Questions"
+type: planning
+tags: [planning, scoping, ai-workflow]
+---
+
+# Open Questions: {{PROJECT_NAME}}
+
+**Date:** {{DATE}}
+**Requested by:** {{AUTHOR}}
+**Status:** Awaiting dev input
+
+---
+
+<!--
+INSTRUCTIONS FOR THE MODEL:
+Your output must be this document with every section filled in. Do not write prose, summaries, or commentary outside the template structure.
+The prompt below describes a project or feature in progress. Generate only the question categories and questions that are genuinely unknown and blocking or likely to affect the implementation.
+- Do not include categories that are fully resolved by the prompt.
+- Each question must have a clear "Why it matters" line so dev understands the impact of their answer.
+- Provide answer scaffolding (checkbox options, blank field, or short list) appropriate to the question type.
+- Do not invent questions for completeness — only ask what is actually unclear.
+- Remove HTML comments from the final output.
+- Do not add, remove, or reorder sections. You may omit entire categories if not relevant.
+- End with the "How to return this doc" section unchanged.
+-->
+
+## Context
+
+> {{PROMPT}}
+
+---
+
+<!-- For each relevant category below, list only the questions that are genuinely unresolved.
+     Omit the entire category block if nothing is unknown in that area. -->
+
+## Scope & Goals
+
+<!-- Q: What is in scope? What is explicitly out? What does "done" look like for v1? -->
+
+**Q1:**
+_Why it matters:_
+- [ ] Option A
+- [ ] Option B
+- [ ] Other: ___
+
+---
+
+## Tech Stack & Environment
+
+<!-- Q: Language, framework, runtime, deployment target, existing codebase constraints -->
+
+**Q1:**
+_Why it matters:_
+Answer: ___
+
+---
+
+## Data & State
+
+<!-- Q: Data sources, storage, schemas, persistence requirements, data ownership -->
+
+**Q1:**
+_Why it matters:_
+Answer: ___
+
+---
+
+## Integrations & Dependencies
+
+<!-- Q: External services, APIs, auth providers, third-party tools -->
+
+**Q1:**
+_Why it matters:_
+Answer: ___
+
+---
+
+## Users & Behavior
+
+<!-- Q: Who uses this? What do they do? Edge cases, error states, permissions -->
+
+**Q1:**
+_Why it matters:_
+Answer: ___
+
+---
+
+## Constraints & Non-Negotiables
+
+<!-- Q: Performance, security, compliance, deadlines, budget, team conventions -->
+
+**Q1:**
+_Why it matters:_
+Answer: ___
+
+---
+
+## How to Return This Doc
+
+Fill in the answers above, then pass this document back as your next prompt.
+You do not need to add context — the filled answers are enough to continue.
+
+---
+
+*Provided by [mdblu](https://github.com/ruco-ai/mdblu)*
+
+---
+*Made with [mdblu](https://github.com/ruco-ai/mdblu) · source: `templates/OPEN-QUESTIONS.md.template`*

package/.flowdeck/_energy/PROJECTINSIGHTS.md.template

@@ -0,0 +1,64 @@
+---
+title: "Project Insights"
+type: metadata
+tags: [metadata, insights, ai-workflow]
+repo: {{PROJECT_NAME}}
+repo_url: {{REPO_URL}}
+last_updated: {{DATE}}
+privacy: local-only
+---
+
+# Project Insights: {{PROJECT_NAME}}
+
+> Accumulated knowledge about this specific codebase. Written by Claude during sessions, read by Claude at session start. Never shared outside this machine — not even in xtage v1's collective pool.
+
+---
+
+## Codebase Quirks
+
+<!-- Non-obvious behavior, surprising implementation choices, things that bit you once -->
+
+-
+
+## Deploy & Operations Notes
+
+<!-- How to run, debug, and deploy. Practical knowledge that isn't in the README -->
+
+-
+
+## Key Architectural Decisions
+
+<!-- Decisions already made that Claude should not second-guess or relitigate -->
+
+| Decision | Rationale |
+|---|---|
+| | |
+
+## Known Issues & Technical Debt
+
+<!-- Things that are broken, fragile, or intentionally deferred. Severity: low / medium / high -->
+
+| Issue | Severity | Notes |
+|---|---|---|
+| | | |
+
+## Refactoring Notes
+
+<!-- Areas that need work and the right approach to take when the time comes -->
+
+-
+
+## Session Log
+
+<!-- Auto-appended by Claude at session end via session-end MCP prompt. Most recent first. -->
+
+| Date | Key learnings from this session |
+|---|---|
+| | |
+
+---
+
+*Generated by xtage {{TOOL_VERSION}} on {{DATE}} — updated by Claude at session end*
+
+---
+*Made with [mdblu](https://github.com/ruco-ai/mdblu) · source: `templates/PROJECTINSIGHTS.md.template`*

package/.flowdeck/_energy/SPEC.md.template

@@ -0,0 +1,101 @@
+---
+title: "Feature Specification"
+type: planning
+tags: [planning, specification, scoping]
+---
+
+# Specification: {{PROJECT_NAME}}
+
+**Date:** {{DATE}}
+**Author:** {{AUTHOR}}
+**Status:** Draft
+
+---
+
+<!--
+INSTRUCTIONS FOR THE MODEL:
+Your output must be this document with every section filled in. Do not write prose, summaries, or commentary outside the template structure.
+The prompt below is a description of a feature, system, or change to be specified. Use it to populate each section.
+- Background & Motivation: explain the why, not restate the prompt.
+- Goals and Non-Goals: explicit and derived from the prompt.
+- Detailed Design: cover data model, interface, and behavior with real content.
+- Fill all tables; add rows as needed.
+- For genuinely unknown information, write "TBD — [what needs to be decided]".
+- Remove HTML comments from the final output.
+- Do not leave generic placeholder text or empty cells.
+- Do not add, remove, or reorder sections.
+-->
+
+## Overview
+
+> {{PROMPT}}
+
+---
+
+## Background & Motivation
+
+<!-- Why is this needed? What problem does it solve? What happens without it? -->
+
+## Goals
+
+-
+-
+
+## Non-Goals
+
+-
+-
+
+## Detailed Design
+
+### Data Model
+
+```
+<!-- Describe entities and fields relevant to this spec -->
+```
+
+### API / Interface
+
+```
+<!-- Function signatures, CLI flags, REST endpoints, or event schemas -->
+```
+
+### Behavior
+
+<!-- Step-by-step description of what the system does, from input to output -->
+
+## Error Handling
+
+<!-- How does the system behave when things go wrong? -->
+
+| Error Case | Behavior | User-Facing Message |
+|------------|----------|---------------------|
+|            |          |                     |
+
+## Security Considerations
+
+<!-- Authentication, authorization, input validation, data privacy -->
+
+## Testing Plan
+
+- [ ] TODO:
+- [ ] TODO:
+
+## Open Questions
+
+<!-- Unresolved decisions that need answers before or during implementation -->
+
+- [ ] TODO:
+
+## Alternatives Considered
+
+| Alternative | Pros | Cons | Decision |
+|-------------|------|------|----------|
+|             |      |      |          |
+
+---
+
+*Provided by [mdblu](https://github.com/ruco-ai/mdblu)*
+
+---
+*Made with [mdblu](https://github.com/ruco-ai/mdblu) · source: `templates/SPEC.md.template`*

package/.flowdeck/_frozen/FROZEN.md

@@ -0,0 +1,4 @@
+# Frozen Cards
+
+| Card | Frozen | Blocking Condition | User Note |
+|------|--------|--------------------|-----------|

package/.flowdeck/_meld/MELD.md

@@ -0,0 +1,4 @@
+# Meld
+
+| Card | Melded | Summary |
+|------|--------|--------|

package/.flowdeck/_stock/STOCK.md

@@ -0,0 +1,4 @@
+# Stock
+
+| Card | Added | Description |
+|------|-------|-------------|

package/.flowdeck/reframe/TODO.md

@@ -0,0 +1,71 @@
+# mcpill
+
+`@ruco-ai/mcpill@1.0.2` is published; `mcpill` unscoped is **free** and needs claiming. CLI for building, validating, and publishing MCP servers using the pill format. Same migration pattern as mcpster and xtage: publish unscoped, deprecate scoped, do not unpublish. Existing package is also missing `repository` and `homepage` metadata — fix on the way through. Move canonical home to `mcpill.ruco.dev`.
+
+## BOT
+
+- [x] Grep repo for all `@ruco-ai/mcpill` and `@ruco-ai/` references (code, docs, examples, CLI help text, generated pill manifests, error messages)
+> Found and updated in package.json, src/commands/{run,pack,init,compile}.ts, src/loaders/prompts.ts, src/__tests__/pack.test.ts, README.md
+- [x] Update `package.json`:
+  - `name`: change from `@ruco-ai/mcpill` to `mcpill`
+  - `homepage`: `https://mcpill.ruco.dev` (currently missing)
+  - `repository`: set to GitHub URL (currently missing — confirm canonical repo path with HUMAN)
+  - `bugs.url`: matching GitHub issues URL (currently missing)
+  - `version`: bump to next minor for the rename milestone (e.g., 1.0.2 → 1.1.0)
+> name → mcpill, version → 1.1.0, homepage/repository/bugs added; deps updated to mcpill-runtime and mcpster (unscoped)
+- [x] Update README:
+  - Install command to `npm install mcpill` (drop scope)
+  - Add "Renamed from `@ruco-ai/mcpill`" note near the top with one-line migration guidance
+  - Refresh any usage examples that show the old scope
+  - Confirm the description matches the package.json description ("CLI for building, validating, and publishing MCP servers using the pill format")
+> Added rename note + migration command; updated pack section to mcpill-runtime (unscoped)
+- [x] Update CLI help strings, error messages, version banner, and example output to use unscoped name
+> Version banner reads dynamically from package.json (no change needed); no other hardcoded scoped strings in CLI layer
+- [x] Audit any generated artifacts (pill manifests, scaffolded files) for hardcoded references to the old scope
+> Updated init.ts (scaffolded tools.js template) and compile.ts (generated tools.js); pack.ts (bin/server.js template + injected dep key)
+- [x] If mcpill depends on or interacts with `mcpster`, ensure the dependency is the unscoped `mcpster` (not `@ruco-ai/mcpster`) in package.json
+> Changed to mcpster in package.json and src/commands/run.ts
+- [x] Add CHANGELOG entry: `1.1.0 — Renamed to mcpill; @ruco-ai/mcpill deprecated; canonical home now mcpill.ruco.dev; repository and homepage metadata added`
+> Created CHANGELOG.md (file didn't exist); entry also notes mcpill-runtime rename
+- [x] Draft GitHub repo description for HUMAN to paste
+> CLI for building, validating, and publishing MCP servers using the pill format.
+
+## HUMAN
+
+- [x] **Prereq:** `ruco.dev` registered, `*.ruco.dev` wildcard DNS configured
+- [x] **Prereq:** mcpster card complete if mcpill depends on it (so the dependency resolves to the unscoped name)
+- [ ] Provision `mcpill.ruco.dev` (landing page or 301 to GitHub README for now)
+- [x] Confirm canonical GitHub repo URL for BOT to set in package.json
+>github.com/ruco-dev/mcpill
+- [x] Is `@ruco-ai/mcpill-runtime` also being renamed (e.g. to `mcpill-runtime`)?
+  > _answer:_yes
+- [x] Review BOT changes
+- [ ] `npm publish` (first publish under the unscoped name — claims it permanently)
+- [ ] `npm deprecate "@ruco-ai/mcpill" "*" "Renamed to mcpill — please install 'mcpill' instead. See https://mcpill.ruco.dev"`
+- [ ] Commit + push
+- [ ] Update GitHub repo description and topics
+- [ ] Verify: `npm view mcpill` shows the new package owned by you; `npm install @ruco-ai/mcpill` shows the deprecation message; `mcpill --version` reports 1.1.0
+
+#### COMMENTS
+
+**Grep task** — `@ruco-ai/mcpster` appears in `package.json` (dependencies) and `src/commands/run.ts:4` (`import { createServer } from "@ruco-ai/mcpster"`). The mcpster card is confirmed complete, so both become `mcpster`. Straightforward find-and-replace.
+
+**`@ruco-ai/mcpill-runtime` is a separate scope** — The card targets `@ruco-ai/mcpill` → `mcpill`, but `@ruco-ai/mcpill-runtime` is a *different package* used heavily throughout:
+- `src/commands/run.ts:3` — runtime import in this CLI
+- `src/commands/pack.ts:7,44-45` — written into the user's generated `bin/server.js` and injected into the user's `package.json` as a dependency
+- `src/commands/init.ts:4` — written into scaffolded `.mcpill/tools.js`
+- `src/commands/compile.ts:18` — written into generated handler stubs
+- `package.json` — both `dependencies` and `devDependencies`
+- `src/__tests__/pack.test.ts:72` — test assertion
+
+**This is the blocking question above.** If `mcpill-runtime` is NOT being renamed in this card, the BOT's "audit generated artifacts" task finds these references but leaves them untouched (correct behavior, documenting a runtime dep). If it IS being renamed, the scope of changes doubles and the test at `pack.test.ts:72` needs updating too.
+
+**`devDependencies` oddity** — `"@ruco-ai/mcpill-runtime": "file:../mcpill/packages/mcpill"` is a local monorepo override for development. The path `../mcpill/packages/mcpill` doesn't appear in this repo's file tree (no `packages/` folder visible). BOT should leave this untouched unless HUMAN clarifies it's broken.
+
+**README is already mostly clean** — `npm install -g mcpill` is already unscoped. The rename note and migration guidance are the only missing pieces. The `### mcpill pack` section documents `@ruco-ai/mcpill-runtime` in the code example — update only if the runtime is also being renamed.
+
+**CLI version banner** — `src/cli.ts:19` reads version dynamically from `package.json`; no hardcoded string to update there.
+
+**CHANGELOG.md doesn't exist** — BOT will need to create the file, not just append to it.
+
+**GitHub repo description draft** — concrete deliverable BOT can do with no dependencies; a one-liner like: `CLI for building, validating, and publishing MCP servers using the pill format.`

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 1.1.0
+
+- Renamed to `mcpill`; `@ruco-ai/mcpill` deprecated — install `mcpill` instead
+- `mcpill-runtime` renamed from `@ruco-ai/mcpill-runtime`
+- Canonical home: https://mcpill.ruco.dev
+- Added `repository`, `homepage`, and `bugs` metadata to package.json

package/FLOWDECK.md

@@ -0,0 +1,17 @@
+# Project
+
+## Vision
+
+<!-- One paragraph describing what this project does and why it exists. -->
+
+## Current state
+
+<!-- Bullet list of shipped capabilities. Update this after each meld. -->
+
+- (no capabilities shipped yet)
+
+## Known gaps
+
+<!-- Open known issues or missing pieces. Update this after each meld. -->
+
+- (none recorded yet)

package/README.md

@@ -0,0 +1,85 @@
+# mcpill
+
+CLI for building, validating, and publishing MCP servers using the pill format.
+
+> **Renamed from `@ruco-ai/mcpill`** — if you have the scoped package, run `npm uninstall -g @ruco-ai/mcpill && npm install -g mcpill`.
+
+## Install
+
+```bash
+npm install -g mcpill
+```
+
+## Author workflow
+
+```
+mcpill init       # scaffold server.md + tools/ + prompts/
+# write your tools, prompts, resources
+mcpill compile    # compile server.md → .<name>/ pill artifact
+mcpill validate   # validate the pill artifact
+mcpill run        # start the MCP server locally (dev)
+mcpill pack       # prepare bin/server.js + package.json for npm
+mcpill publish    # pack + npm publish
+```
+
+## Commands
+
+### `mcpill init`
+
+Scaffolds a new project in the current directory:
+
+- `server.md` — Config + Resources in human-readable Markdown
+- `tools/echo.md` — example tool
+- `prompts/greeting.md` — example prompt
+- `.mcpill/` — pre-compiled pill artifact
+- `package.json` — with `pack` and `publish` scripts ready
+
+### `mcpill compile`
+
+Compiles `server.md` + `tools/*.md` + `prompts/*.md` into a `.<name>/` pill artifact.
+
+```bash
+mcpill compile              # forward: source → pill
+mcpill compile --to-md      # reverse: pill → source
+mcpill compile --strict     # error on missing tool handlers (default: stub)
+```
+
+### `mcpill validate`
+
+Validates all pill directories (`.<name>/`) in the project root.
+
+### `mcpill run`
+
+Starts the MCP server from the pill artifact.
+
+```bash
+mcpill run                        # stdio (default)
+mcpill run --transport http --port 3333
+```
+
+### `mcpill pack`
+
+Prepares the pill for npm distribution:
+
+1. Validates the pill artifact
+2. Writes `bin/server.js`:
+
+```js
+import { runPill } from 'mcpill-runtime';
+runPill();
+```
+
+3. Merges into `package.json`: sets `type: "module"`, `bin`, and `dependencies["mcpill-runtime"]`. Does not overwrite existing `name` or `version`.
+
+### `mcpill publish`
+
+Runs `mcpill pack` then publishes to npm.
+
+```bash
+mcpill publish                    # npm publish --access public
+mcpill publish --access restricted
+```
+
+## Options
+
+All commands accept `--dir <path>` to target a directory other than the current working directory.