Distribution & showcase: topics, issues, contributing, directory prep

- Add 14 GitHub topics for discoverability (zatca, mcp, saudi-arabia, etc.)
- Set homepage URL to fikrah.ai
- Create 4 GitHub issues (3 good-first-issue) to invite contributors
- Add CONTRIBUTING.md with setup and contribution guide
- Add "Built with zatca-mcp" section to README with Fikrah breadcrumb
- Add Contributing section to README linking to good first issues
- Improve demo placeholder with natural language example
- Add glama.json for Glama.ai directory ownership claim
- Add DIRECTORY_SUBMISSIONS.md with exact copy-paste content for
  punkpeye/awesome-mcp-servers, mcpservers.org, and Glama.ai
- server.py: add render_invoice_html tool, update to instructions field

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: BloqAITeam

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to ZATCA MCP
+
+Thanks for your interest in contributing! This is the first open-source MCP server for Saudi e-invoicing, and contributions are welcome.
+
+## Getting Started
+
+```bash
+git clone https://github.com/DoubleH10/zatca-mcp.git
+cd zatca-mcp
+pip install -e ".[dev,phase2]"
+```
+
+## Running Tests
+
+```bash
+pytest tests/ -v                         # All tests
+pytest tests/ -v -m "not sandbox"        # Skip live ZATCA sandbox tests
+```
+
+## Code Quality
+
+We use ruff for linting/formatting and mypy for type checking:
+
+```bash
+ruff check src/ tests/
+ruff format --check src/ tests/
+mypy src/zatca_mcp/ --ignore-missing-imports
+```
+
+All checks run in CI across Python 3.10, 3.11, and 3.12.
+
+## Making Changes
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes
+3. Add or update tests as needed
+4. Ensure all tests pass and linting is clean
+5. Open a PR with a clear description of what you changed and why
+
+## Good First Issues
+
+Check the [good first issue](https://github.com/DoubleH10/zatca-mcp/labels/good%20first%20issue) label for beginner-friendly tasks.
+
+## Questions?
+
+Open an issue or start a discussion. We're happy to help you get started.

DIRECTORY_SUBMISSIONS.md

@@ -0,0 +1,75 @@
+# MCP Directory Submissions Checklist
+
+Action items for getting zatca-mcp listed across MCP directories.
+
+---
+
+## 1. punkpeye/awesome-mcp-servers (PR) — DO FIRST
+
+**This is the highest-impact listing. Glama.ai auto-syncs from it.**
+
+1. Fork https://github.com/punkpeye/awesome-mcp-servers
+2. Edit `README.md` — find the `## Finance & Fintech` section
+3. Add this line in alphabetical order (after entries starting with "D"):
+
+```markdown
+- [DoubleH10/zatca-mcp](https://github.com/DoubleH10/zatca-mcp) 🐍 ☁️ - ZATCA e-invoicing for Saudi Arabia. Generate, validate, sign, and submit tax-compliant XML invoices via MCP.
+```
+
+4. Submit PR with title: `Add zatca-mcp — ZATCA e-invoicing server for Saudi Arabia`
+5. PR description:
+
+```
+Adds zatca-mcp to the Finance & Fintech category.
+
+- First MCP server for Saudi Arabia's ZATCA e-invoicing mandate
+- 8 MCP tools: generate, validate, sign, submit invoices + QR codes
+- UBL 2.1 XML, 16-rule validation engine, XAdES-BES signing
+- Phase 1 + Phase 2 ZATCA compliance
+- 100 tests, CI/CD, Python 3.10-3.12, Apache 2.0
+- pip-installable: `pip install zatca-mcp`
+```
+
+---
+
+## 2. mcpservers.org (web form) — DO SECOND
+
+**This also feeds wong2/awesome-mcp-servers automatically.**
+
+Go to: https://mcpservers.org/submit
+
+Fill in:
+
+| Field | Value |
+|-------|-------|
+| Server Name | `ZATCA MCP` |
+| Short Description | `ZATCA e-invoicing for Saudi Arabia — generate, validate, sign, and submit tax-compliant XML invoices from natural language. 8 MCP tools, UBL 2.1, 16-rule validation, XAdES-BES signing, Phase 1 + Phase 2 support.` |
+| Link | `https://github.com/DoubleH10/zatca-mcp` |
+| Category | `cloud-service` (closest option — connects to ZATCA APIs) |
+| Contact Email | `hadi.hijazi@bloqmedia.net` |
+
+---
+
+## 3. Glama.ai — DO AFTER punkpeye PR merges
+
+Glama auto-syncs from punkpeye/awesome-mcp-servers. Once listed:
+
+1. `glama.json` is already in the repo root (done)
+2. Go to https://glama.ai and authenticate with GitHub
+3. Search for zatca-mcp and claim ownership
+
+---
+
+## 4. mcp-awesome.com — SKIP FOR NOW
+
+Likely auto-aggregates from other directories. No clear submission mechanism.
+Check back after the punkpeye and mcpservers.org listings are live.
+
+---
+
+## Status
+
+- [ ] punkpeye/awesome-mcp-servers PR submitted
+- [ ] mcpservers.org form submitted
+- [ ] Glama.ai ownership claimed
+- [ ] mcp-awesome.com (auto or manual)

README.md

@@ -13,8 +13,10 @@
 
 </div>
 
-<!-- screenshot: add asciinema/VHS terminal recording here -->
-<!-- <p align="center"><img src="docs/demo.gif" width="700" alt="Fikra CLI demo"></p> -->
+<!-- TODO: Record a 30-second demo GIF of Claude Desktop generating a ZATCA invoice via natural language -->
+<!-- <p align="center"><img src="docs/demo.gif" width="700" alt="Generate a ZATCA-compliant invoice from natural language"></p> -->
+
+<p align="center"><em>"Generate an invoice for 10 hours of consulting at 500 SAR to Al-Rajhi Corp"</em> &rarr; compliant XML + QR code in seconds</p>
 
 ---
 
@@ -510,10 +512,17 @@ mcp dev src/zatca_mcp/server.py
 - [ ] HTTP/SSE transport
 - [ ] Arabic RTL invoice template
 
-## Built by Fikrah
+## Built with zatca-mcp
+
+| Project | Description |
+|---------|-------------|
+| [Fikrah](https://fikrah.ai) | Agentic AI workforce for financial operations — uses this server as its ZATCA compliance backbone |
+
+> Using zatca-mcp in your project? Open a PR to add it here.
+
+## Contributing
 
-[Fikrah](https://fikrah.ai) is building an agentic AI workforce for financial operations.
-This MCP server is the foundation for our Saudi e-invoicing capabilities.
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions. Check the [good first issues](https://github.com/DoubleH10/zatca-mcp/labels/good%20first%20issue) for a place to start.
 
 ## License
 

glama.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": [
+    "DoubleH10"
+  ]
+}

src/zatca_mcp/server.py

@@ -31,11 +31,10 @@
 # Create the MCP server
 mcp = FastMCP(
     "zatca-mcp",
-    description=(
+    instructions=(
         "ZATCA e-invoicing MCP server for Saudi Arabia. "
         "Generate, validate, and manage compliant electronic invoices."
     ),
-    version="0.1.0",
 )
 
 
@@ -602,6 +601,31 @@ async def check_compliance(
         return json.dumps({"error": f"ZATCA compliance check failed: {str(e)}"})
 
 
+# ═══════════════════════════════════════════════════
+# TOOL 9: HTML Invoice Rendering
+# ═══════════════════════════════════════════════════
+
+@mcp.tool()
+async def render_invoice_html(invoice_xml: str) -> str:
+    """Render a ZATCA invoice XML as a professional HTML document.
+
+    Takes a UBL 2.1 XML invoice (as generated by generate_invoice) and
+    produces a styled HTML page with embedded QR code image, ready for
+    viewing in a browser or printing.
+
+    Args:
+        invoice_xml: Complete UBL 2.1 XML invoice string
+
+    Returns:
+        Complete HTML document string with embedded styles and QR code image
+    """
+    try:
+        from zatca_mcp.cli import generate_html_invoice
+        return generate_html_invoice(invoice_xml)
+    except Exception as e:
+        return json.dumps({"error": f"HTML rendering failed: {str(e)}"})
+
+
 def main():
     """Entry point for the ZATCA MCP server."""
     mcp.run()