feat: add mempool.space public api skill

[jolestar]

What

Add a mempool-space-openapi-skill wrapper for mempool.space public Bitcoin and Lightning explorer APIs through UXC.

Why

Issue #168 surfaced a Bitcoin / Lightning coverage gap from follow-up comments. mempool.space gives us a practical no-auth public surface with stable Bitcoin explorer routes plus Lightning network reads, which is a good first provider to close that gap.

Closes #316

How

Create a thin wrapper skill with a curated OpenAPI schema instead of exposing the full mempool.space explorer surface. Scope v1 to public read-only endpoints for fee recommendations, mempool summary, block tip, address summary, transaction status, and selected Lightning reads.

Changes

• Add skills/mempool-space-openapi-skill with SKILL.md, agents/openai.yaml, references/usage-patterns.md, and scripts/validate.sh
• Add a curated mempool-space-public.openapi.json schema for public Bitcoin and Lightning reads
• Document explorer-specific guardrails, including the current channel-id route quirk on Lightning channel detail
• Update docs/skills.md catalog, install guidance, and validation commands

Testing

Unit Tests

• All existing tests pass
• New tests added (if applicable)
• cargo test passes

Manual Testing

• Tested against real APIs
• Tested edge cases
• Tested error conditions

Test Results

bash skills/mempool-space-openapi-skill/scripts/validate.sh
cargo fmt --check
/Users/jolestar/opensource/src/github.com/holon-run/uxc/target/debug/uxc \
  https://mempool.space/api \
  --schema-url file:///tmp/uxc-mempool/skills/mempool-space-openapi-skill/references/mempool-space-public.openapi.json \
  get:/v1/fees/recommended
/Users/jolestar/opensource/src/github.com/holon-run/uxc/target/debug/uxc \
  https://mempool.space/api \
  --schema-url file:///tmp/uxc-mempool/skills/mempool-space-openapi-skill/references/mempool-space-public.openapi.json \
  get:/v1/lightning/search searchText=bfx

Checklist

• Code formatted with cargo fmt
• No clippy warnings (cargo clippy -- -D warnings)
• All tests pass (cargo test)
• Documentation updated
• Commit messages follow convention
• PR title follows convention (e.g., feat: add GraphQL support)

Breaking Changes

None.

Additional Notes

The scope intentionally stays smaller than the full Esplora-compatible API. The goal is to cover the highest-value Bitcoin and Lightning public reads without creating a broad overlapping skill that is harder to maintain.

[holonbot]

PR Review: feat: add mempool.space public api skill

Summary

This PR adds a new mempool-space-openapi-skill wrapper for mempool.space's public Bitcoin and Lightning explorer APIs. The implementation follows established patterns from similar skills (e.g., coinapi-openapi-skill) and includes comprehensive documentation, validation, and guardrails.

Overall Assessment: LGTM with minor suggestions

The PR is well-structured, thoroughly documented, and follows the project's skill conventions. The code quality is high, with proper validation scripts and clear usage examples.

Key Findings

✅ Strengths

1. Follows established patterns: The skill structure closely matches existing OpenAPI skills (coinapi-openapi-skill), maintaining consistency across the codebase.

2. Comprehensive documentation:

   • Clear scope boundaries (what's included vs. excluded)
   • Detailed usage examples in references/usage-patterns.md
   • Proper guardrails documentation, including API-specific quirks

3. Proper validation: The validate.sh script includes thorough checks for:

   • Required files presence
   • OpenAPI schema structure
   • Required documentation elements
   • Guardrails presence

4. No-auth setup: Correctly identifies that mempool.space public reads don't require authentication, simplifying the user experience.

5. Curated schema: Instead of exposing the full Esplora-compatible API, the PR thoughtfully selects high-value endpoints for Bitcoin and Lightning operations.

6. Integration updates: Properly updates docs/skills.md with catalog entry, installation guidance, and validation commands.

⚠️ Minor Issues

1. Test checkbox incomplete (docs/skills.md:18):

   • The PR description shows [ ] All tests pass (\cargo test`)` as unchecked
   • However, this is a documentation-only PR with no Rust code changes, so cargo test is not applicable
   • Recommendation: Update the checklist to clarify that no Rust tests are needed for this skill

2. Clippy warnings unchecked (docs/skills.md:18):

   • Similar to above, cargo clippy is marked as unchecked but not applicable
   • Recommendation: Same as above - clarify or remove these checkboxes for documentation-only skills

3. Schema response validation (mempool-space-public.openapi.json:152-462):

   • All response schemas use additionalProperties: true, which provides no type safety
   • While this follows the pattern from coinapi-openapi-skill, it means consumers get no schema validation for response structures
   • Note: This is acceptable for v1 but should be documented as a known limitation for future enhancement

Detailed Analysis

Code Quality

• SKILL.md: Well-structured with clear sections for prerequisites, scope, authentication, workflow, operations, and guardrails
• OpenAPI schema: Valid OpenAPI 3.0.3 with proper path definitions and parameter schemas
• usage-patterns.md: Comprehensive examples covering all documented operations
• validate.sh: Robust validation with clear error messages

Security & Safety

• ✅ Read-only operations only (no transaction broadcast or write operations)
• ✅ No authentication required (reduces attack surface)
• ✅ Guardrails explicitly warn against using tx/push or package submission
• ✅ API-specific quirks documented (e.g., Lightning channel id vs short_id)

Maintainability

• ✅ Clear separation of concerns (docs, schema, validation, agent config)
• ✅ Consistent with existing skill patterns
• ✅ Validation script prevents regressions
• ✅ Usage examples serve as both documentation and tests

Recommendations

Before Merge

None - the PR is ready to merge.

Future Enhancements

1. Add response schemas: Consider adding typed response schemas in a future iteration for better validation
2. Rate limiting guidance: Document if mempool.space has rate limits for public APIs
3. Error handling examples: Add examples of handling common error responses in usage patterns

Testing Validation

The PR demonstrates manual testing with real API calls:

• ✅ get:/v1/fees/recommended - Bitcoin fee recommendations
• ✅ get:/v1/lightning/search - Lightning network search
• ✅ Validation script passes all checks

Conclusion

This is a high-quality PR that adds valuable Bitcoin/Lightning explorer capabilities to UXC. The implementation is thorough, well-documented, and follows project conventions. The minor issues identified are documentation clarifications rather than code problems.

Recommendation: Approve for merge after clarifying the test checklist items (or noting they're N/A for documentation-only changes).

[holonbot]

Minor Suggestion

docs/skills.md:18 - The test checklist shows cargo test and cargo clippy as unchecked, but this PR only adds documentation with no Rust code changes. Consider clarifying these items are N/A for documentation-only skills.

Overall, great work on this PR! The implementation is thorough and follows project conventions well.

[Copilot]

Pull request overview

Adds a new curated OpenAPI wrapper skill for the public mempool.space Bitcoin + Lightning explorer API, expanding the repo’s crypto data coverage via UXC without requiring authentication.

Changes:

• Introduces skills/mempool-space-openapi-skill (docs, agent config, curated schema, and validator).
• Adds a curated OpenAPI schema covering a small set of high-value read-only Bitcoin + Lightning endpoints.
• Updates the skills catalog documentation to include installation and validation guidance for the new skill.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
skills/mempool-space-openapi-skill/scripts/validate.sh	Adds repo-standard validation checks for required files, schema shape/paths, and doc guardrails.
skills/mempool-space-openapi-skill/references/usage-patterns.md	Provides link setup and concrete CLI usage examples for the curated endpoints.
skills/mempool-space-openapi-skill/references/mempool-space-public.openapi.json	Adds curated OpenAPI 3.0.3 schema for selected public Bitcoin + Lightning read operations.
skills/mempool-space-openapi-skill/agents/openai.yaml	Defines the agent interface metadata and default prompt for the skill.
skills/mempool-space-openapi-skill/SKILL.md	Adds skill overview, scope, workflow, operations list, and explorer-specific guardrails.
docs/skills.md	Adds the new skill to the catalog and documents its validator command.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.