docs: Prepare repository for open source publication #28

michael-airspace · 2025-10-09T16:10:18Z

Summary

This PR prepares the repository for public open source release by adding required community health files, updating documentation to meet open source standards, and renaming the project to Hoopoe.

Changes

Project Rename

Repository: Renamed from mcp_tools to hoopoe
Package name: Changed from mcp-codex-tools to hoopoe in pyproject.toml
Logo: Added hoopoe bird logo to README
Documentation: Updated all references throughout the codebase
Name meaning: The hoopoe is a mythical messenger bird that bridged communication between Solomon and the Queen of Sheba, representing wisdom, mediation, and protocol - perfectly capturing this tool's role as a bridge between AI systems

New Community Health Files

CODE_OF_CONDUCT.md: Adds Contributor Covenant v2.1 to establish community standards
SECURITY.md: Defines vulnerability reporting process and security considerations for users

Documentation Updates

CONTRIBUTING.md: Updated repository URLs to use new hoopoe name
README.md:
- Added hoopoe logo with centered display
- Restructured for open source audience with focus on multi-agent orchestration
- Added multi-agent architecture diagram illustrating orchestration patterns
- Moved disclaimer to bottom and expanded to include all trademarks (OpenAI, Anthropic, Google)
- Added badges (CI status, MIT license, Python 3.10+)
- Emphasized Claude Code orchestrator pattern
- Added session strategy guidance (new vs reuse)
- Updated all repository URLs
- Fixed file path reference to tests/fixtures/codex_tool_examples.yaml
CLAUDE.md:
- Updated project overview with hoopoe name and meaning
- Fixed port inconsistencies (8001 → 8957) in all CLI examples
- Added worktree parameter to quickstart Inspector command
- Fixed tool name references (codex_reply → reply)
LICENSE: Updated copyright to hoopoe contributors
pyproject.toml:
- Renamed package from mcp-codex-tools to hoopoe
- Fixed PEP 621 compliance: Moved repository URL to [project.urls] section
- Updated repository URL and contributors
- Added complete metadata: authors, license, repository URL, readme reference
SECURITY.md: Clarified when to use private security advisories vs public issues
tests/test_mcp_client.py:
- Updated test to use correct tool name (reply)
- Fixed test tool name mismatch (python_assistant → coding_assistant)
src/mcp_server.py: Added explicit host="127.0.0.1" binding for defense-in-depth
docs/HOW_THIS_SOLVES_REAL_PROBLEMS.md: Fixed tool name in examples

New Documentation Files

docs/AGENT_PATTERNS.md: Multi-agent orchestration patterns and backend support matrix
docs/CONFIGURATION.md: Complete tool reference, parameters, and validation details
docs/EXAMPLES.md: End-to-end workflow examples
docs/TROUBLESHOOTING.md: Common errors and solutions
docs/images/gemini_multi_agent.png: Visual diagram of multi-agent architecture patterns

All PR Feedback Addressed

First Round:

✅ Port inconsistency (8001 vs 8957) corrected in CLAUDE.md
✅ Worktree parameter added to quickstart with explanatory note
✅ Tool name (codex_reply → reply) fixed in all files
✅ PEP 621 compliance: Repository URL moved to [project.urls]
✅ File path corrected in README (tests/fixtures/codex_tool_examples.yaml)
✅ Security policy clarified (private advisories vs public issues)
✅ Package name consistency (uv.lock regenerated with "hoopoe")

Second Round:

✅ Test tool name mismatch fixed (python_assistant → coding_assistant)
✅ Explicit host binding added (host="127.0.0.1") for defense-in-depth

Why These Changes

The rename to "hoopoe" provides:

A meaningful, memorable name with thematic connection to the tool's purpose (bridging/messaging)
Consistency with AirspaceTechnologies' bird-themed naming convention
Visual identity through the logo
Cultural resonance that captures the tool's role as a protocol bridge

The community health files and documentation updates help:

Establish clear community expectations and standards of conduct
Provide security vulnerability reporting guidelines
Clarify legal status and trademark considerations for all mentioned tools
Make the project more discoverable and trustworthy
Signal that the project is production-ready
Ensure documentation accuracy and PEP compliance
Provide comprehensive guidance for multi-agent orchestration patterns
Visual clarity through architecture diagrams

Verification

🤖 Generated with Claude Code

Add community health files and update documentation to meet open source standards and best practices. ## Changes ### New Files - Add CODE_OF_CONDUCT.md with Contributor Covenant v2.1 - Add SECURITY.md with vulnerability reporting policy and security guidelines ### Updated Files - Update CONTRIBUTING.md: Replace placeholder repository URL with actual URL - Update pyproject.toml: - Rename package from "mcp-codex-poc" to "mcp-codex-tools" - Add metadata: authors, license, repository URL, readme - Update README.md: - Add disclaimer about unofficial/third-party status - Add badges for CI status, license, and Python version These changes prepare the repository for public open source release with proper community documentation and clear licensing information. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

- Rename GitHub repository to hoopoe (messenger bird from mythology) - Update package name in pyproject.toml to hoopoe - Add hoopoe logo to README with centered display - Update all documentation (README, CLAUDE.md, CONTRIBUTING, SECURITY, LICENSE) - Update repository URLs throughout to use new name - Add name etymology explaining the mythological significance The hoopoe is a mythical messenger bird that bridged communication between Solomon and the Queen of Sheba, representing wisdom, mediation, and protocol - perfectly capturing this tool's role as a bridge between AI systems. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

… PEP 621 compliance - Fix port inconsistency: Replace 8001 with 8957 in all CLI examples (CLAUDE.md) - Add worktree parameter to quickstart MCP Inspector command with note - Fix tool name: Replace codex_reply with reply throughout docs and tests - Fix PEP 621 compliance: Move repository URL to [project.urls] section - Fix file path: Update README to reference tests/fixtures/codex_tool_examples.yaml - Improve security policy clarity: Distinguish private advisories vs public issues - Regenerate uv.lock with correct package name (hoopoe) All changes address documentation consistency issues identified in PR review. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

- Fix test tool name mismatch: python_assistant → coding_assistant (tests/test_mcp_client.py) - Add explicit host binding for defense-in-depth: host="127.0.0.1" (src/mcp_server.py) - Restructure README for open source audience (README.md): - Streamlined overview focusing on multi-agent orchestration use case - Added agent pattern documentation reference - Reorganized sections for better discoverability - Emphasized Claude Code orchestrator pattern - Added session strategy guidance - Add comprehensive documentation files: - docs/AGENT_PATTERNS.md: Multi-agent patterns and backend support matrix - docs/CONFIGURATION.md: Complete tool reference and parameters - docs/EXAMPLES.md: End-to-end workflow examples - docs/TROUBLESHOOTING.md: Common errors and solutions All feedback items now addressed with improved documentation structure. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Add visual illustration of multi-agent patterns (single, network, supervisor, hierarchical, custom) from Gemini documentation to help readers understand the orchestration capabilities Hoopoe enables. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Move disclaimer from top of README to bottom (traditional placement for legal/trademark notices) and expand to include all three tools/companies mentioned in documentation: - OpenAI/Codex - Anthropic/Claude Code - Google/Gemini 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

michael-airspace and others added 6 commits October 9, 2025 09:09

michael-airspace merged commit f8bf33e into main Oct 9, 2025
1 check passed

michael-airspace deleted the docs/prepare-for-open-source branch October 9, 2025 17:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: Prepare repository for open source publication #28

docs: Prepare repository for open source publication #28

Uh oh!

michael-airspace commented Oct 9, 2025 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

docs: Prepare repository for open source publication #28

docs: Prepare repository for open source publication #28

Uh oh!

Conversation

michael-airspace commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Project Rename

New Community Health Files

Documentation Updates

New Documentation Files

All PR Feedback Addressed

Why These Changes

Verification

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

michael-airspace commented Oct 9, 2025 •

edited

Loading