get_policy

Instructions

Implementation Reference

• src/asf_policy_mcp/tools.py:42-59 (handler)

  The 'get_policy' tool handler function. Defined as an @mcp.tool() in the FastMCP server. Takes a policy key and optional force_refresh flag, validates the key against POLICY_SOURCES, loads cache, fetches policy text via fetcher.get_policy_text(), and returns formatted markdown with title, source URL, section, and policy text.

  @mcp.tool()
  def get_policy(key: str, force_refresh: bool = False) -> str:
      """Retrieve the full text of a specific ASF policy document.
  
      Use list_policies to discover valid policy keys such as 'release_policy',
      'branding', 'resolved_licenses', 'incubator', etc.
      """
      if key not in POLICY_SOURCES:
          available = ", ".join(f"`{k}`" for k in POLICY_SOURCES)
          return f"Unknown policy key **{key!r}**. Available keys: {available}"
      cache = fetcher.load_cache()
      meta = POLICY_SOURCES[key]
      text = fetcher.get_policy_text(key, cache, force=force_refresh)
      return (
          f"# {meta['title']}\n\n"
          f"**Source:** <{meta['url']}>\n"
          f"**Section:** {meta['section']}\n\n---\n\n"
      ) + text

• src/asf_policy_mcp/tools.py:42-42 (registration)

  Registration via @mcp.tool() decorator on the get_policy function, registering it with the FastMCP server instance named 'asf-policy'.

  @mcp.tool()

• src/asf_policy_mcp/fetcher.py:63-73 (helper)

  The get_policy_text helper function that implements cache logic. Returns cached text if fresh (within 30-day TTL) and not forced, otherwise fetches from the web via fetch_page_text(), saves to cache, and returns the text.

  def get_policy_text(key: str, cache: dict[str, Any], force: bool = False) -> str:
      """Return policy text from *cache*, fetching from the web if stale or missing."""
      entry: dict[str, Any] = cache.get(key, {})
      now = time.time()
      if not force and entry.get("text") and now - float(entry.get("fetched_at", 0)) < CACHE_TTL:
          return str(entry["text"])
      url = POLICY_SOURCES[key]["url"]
      text = fetch_page_text(url)
      cache[key] = {"text": text, "fetched_at": now, "url": url}
      save_cache(cache)
      return text

• src/asf_policy_mcp/sources.py:5-126 (schema)

  The POLICY_SOURCES dictionary that defines all valid policy keys, titles, URLs, sections, and descriptions. Used by get_policy to validate the key and retrieve metadata like title and URL for the response.

  POLICY_SOURCES: dict[str, dict[str, str]] = {
      "pmc": {
          "title": "PMC Guide (Mailing Lists, Committers, PMC Members)",
          "url": "https://www.apache.org/dev/pmc.html",
          "section": "Community And Project Oversight",
          "description": "Rules for mailing lists, adding committers, and managing PMC membership",
      },
      "project_independence": {
          "title": "Project Independence",
          "url": "https://community.apache.org/projectIndependence.html",
          "section": "Independence",
          "description": "Guidelines for operating independently and for the public good",
      },
      "board_reporting": {
          "title": "Board Reporting Requirements",
          "url": "https://www.apache.org/foundation/board/reporting",
          "section": "Reporting",
          "description": "Quarterly board status report requirements for PMCs",
      },
      "release_policy": {
          "title": "Release Policy",
          "url": "https://www.apache.org/legal/release-policy",
          "section": "Release",
          "description": "Apache software release policy - what constitutes a valid release",
      },
      "voting": {
          "title": "Apache Voting Process",
          "url": "https://www.apache.org/foundation/voting.html",
          "section": "Release",
          "description": "Apache voting process for releases and other decisions",
      },
      "release_distribution": {
          "title": "Release Distribution Policy",
          "url": "https://www.apache.org/dev/release-distribution",
          "section": "Release",
          "description": "Policy for how and where Apache releases are distributed",
      },
      "security": {
          "title": "Security Team Guidance",
          "url": "https://www.apache.org/security/",
          "section": "Security",
          "description": "Security notification and disclosure procedures",
      },
      "security_committers": {
          "title": "Vulnerability Handling for Committers",
          "url": "https://www.apache.org/security/committers.html",
          "section": "Security",
          "description": "How committers should handle reported security vulnerabilities",
      },
      "licenses": {
          "title": "Contributor License Agreements (CLAs)",
          "url": "https://www.apache.org/licenses/",
          "section": "Licensing",
          "description": "CLA requirements and Apache license versions",
      },
      "source_headers": {
          "title": "Apache Source Headers",
          "url": "https://www.apache.org/legal/src-headers.html",
          "section": "Licensing",
          "description": "Required Apache license headers in source files",
      },
      "resolved_licenses": {
          "title": "Approved/Resolved Third-Party Licenses",
          "url": "https://www.apache.org/legal/resolved.html",
          "section": "Licensing",
          "description": "Which third-party licenses are Category A (allowed), B (limited), or X (forbidden)",
      },
      "branding": {
          "title": "Project Branding Requirements",
          "url": "https://www.apache.org/foundation/marks/pmcs",
          "section": "Branding",
          "description": "Trademark and branding requirements for PMC projects",
      },
      "trademark_maintenance": {
          "title": "Trademark Maintenance Responsibilities",
          "url": "https://www.apache.org/foundation/marks/responsibility.html",
          "section": "Branding",
          "description": "PMC responsibilities for maintaining Apache trademarks",
      },
      "website_linking": {
          "title": "Website Linking Policy",
          "url": "https://www.apache.org/foundation/marks/linking",
          "section": "Branding",
          "description": "Policy on linking to and from Apache project websites",
      },
      "repo_policy": {
          "title": "Repository Policy",
          "url": "https://infra.apache.org/project-repo-policy.html",
          "section": "Infrastructure",
          "description": "Policy for project source code repositories",
      },
      "website_policy": {
          "title": "Website Policy",
          "url": "https://infra.apache.org/project-site-policy.html",
          "section": "Infrastructure",
          "description": "Policy for project websites and hosting",
      },
      "press": {
          "title": "Press & Marketing Policy",
          "url": "https://www.apache.org/press/",
          "section": "Press",
          "description": "Guidelines for press releases and marketing coordination",
      },
      "sponsorship": {
          "title": "Sponsorship Requirements",
          "url": "https://www.apache.org/foundation/sponsorship.html",
          "section": "Fundraising",
          "description": "Fundraising and sponsorship policies",
      },
      "privacy": {
          "title": "Privacy Policy",
          "url": "https://privacy.apache.org/policies/privacy-policy-public.html",
          "section": "Privacy",
          "description": "ASF privacy policy",
      },
      "incubator": {
          "title": "Incubator Podling Policies",
          "url": "https://incubator.apache.org/policy/incubation.html",
          "section": "Incubator",
          "description": "Policies governing Apache Incubator podlings",
      },
  }