cloudflare / cloudflare/cloudflare-os

Document the exact portal_list_servers response format the MCP Server Portals connector parses

Open Beginner friendly
#486 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
9.9k
Forks
1.2k
Avg merge
1d 20h
Merged PRs (30d)
107

Description

**Context**
`packages/gatekeeper-mcp-portal/README.md` describes the portal contract as two facts: tools are named `{server_id}_{original_name}` (split on the first underscore), and `portal_list_servers` "returns each upstream server's id, name, and enabled state". The second fact is not specific enough to implement against.

The actual parser (`packages/mcp-shared/src/portal.ts`, `parseServerLine` / `parsePortalServers`) accepts either:

- `structuredContent: { servers: [{ id, name, enabled }] }`, or
- text content with bullet lines of the form `- {display name} ({server id}): {status}`, where the status is treated as disabled when it contains "disabled", "✗" or "✘", e.g.

```
Available MCP Servers:

- Mini DWH (dwh): ✓ enabled
- Mini ERP (erp): ✓ enabled
```

Unrecognized lines are skipped and the listing is marked incomplete.

**Why it matters**
We put a self-hosted gateway (agentgateway) in front of our MCP servers. It already emits the `{target}_{tool}` prefix, so the only missing piece was a `portal_list_servers` tool. Getting its output accepted required reading the parser source. With the format documented, third-party gateways and small adapters can implement the portal contract without guessing.

**Suggestion**
Add the two accepted shapes (structured and text) and the disabled-status rule to the "How upstream servers are recovered" section of the connector README, next to the naming rule. Mentioning that `portal_*` tools are never grantable would round it out.

**Environment**
cloudflare-os main @ c0b6f3e (2026-09-04); the README on current main still describes the response only as "id, name, and enabled state".

Contributor guide

Open the contributing guide

Research direction

Start with packages/gatekeeper-mcp-portal/README.md and its “How upstream servers are recovered” section, then read parseServerLine and parsePortalServers in packages/mcp-shared/src/portal.ts. Confirm the README covers both structuredContent and text responses, the disabled-status rule, skipped lines, incomplete listings, and the portal_* grantability note. Done means a third-party gateway can implement portal_list_servers without reading parser source.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
90/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.