Condense README, add Homebrew install by turlockmike · Pull Request #57 · turlockmike/murl

turlockmike · 2026-02-20T23:54:44Z

Summary

README cut from 423 → 133 lines
Homebrew is now the recommended install method
Added OAuth quick reference
Detailed docs moved to docs/:
- docs/agent-mode.md — NDJSON, structured errors, exit codes
- docs/mcp-servers.md — mcp-proxy setup, Streamable HTTP
- docs/contributing.md — dev setup, how it works, releasing

Test plan

Verify all doc links resolve on GitHub
README renders correctly

- README: 423 lines → 133 lines - Homebrew install is now the first/recommended option - Added OAuth section - Moved agent mode, MCP server setup, and contributing to docs/ Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

This PR restructures the murl documentation to be more concise and better organized. The README is condensed from 423 to 133 lines, with detailed content moved to topic-specific files in a new docs/ directory. Homebrew is now positioned as the recommended installation method.

Changes:

README streamlined to focus on quick start and essential usage, with detailed content moved to separate documentation files
Added three new documentation files covering agent mode, MCP server setup, and contributing guidelines
Homebrew installation promoted to primary method with updated upgrade instructions

Reviewed changes

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

File	Description
README.md	Condensed from 423 to 133 lines; reorganized with Homebrew as recommended install; added OAuth quick reference; links to detailed docs
docs/agent-mode.md	New file documenting agent mode behavior, exit codes, and NDJSON output (references non-existent `--agent` flag)
docs/mcp-servers.md	New file covering MCP server setup, mcp-proxy usage, and Streamable HTTP support
docs/contributing.md	New file with development setup, testing, architecture overview, and release process

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

Copilot · 2026-02-20T23:59:42Z

docs/agent-mode.md

+# Agent Mode
+
+murl implements [POSIX Agent Standard (Level 2)](https://github.com/turlockmike/posix-agent-standard) for AI agent compatibility. Use `--agent` to enable.
+
+## Behavior
+
+- **Pure JSON output:** Compact JSON to stdout (no pretty-printing)
+- **JSON Lines (NDJSON):** List operations output one JSON object per line
+- **Structured errors:** JSON error objects to stderr with error codes
+- **Non-interactive:** No prompts or progress indicators
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | General error (connection, timeout, server error) |
+| `2` | Invalid arguments (malformed URL, invalid data format) |
+| `100` | MCP server error (reported via JSON `code` field, not exit code) |
+
+## Examples
+
+```bash
+# Agent-optimized help
+murl --agent --help
+
+# List tools (NDJSON — one JSON object per line)
+murl --agent http://localhost:3000/tools
+
+# Call a tool (compact JSON)
+murl --agent http://localhost:3000/tools/echo -d message=hello
+
+# Process with jq
+murl --agent http://localhost:3000/tools | jq -c '.'
+
+# Handle errors programmatically
+if ! result=$(murl --agent http://localhost:3000/tools/invalid 2>&1); then
+  echo "Error: $result" | jq -r '.message'
+fi
+```
+
+## Human Mode vs Agent Mode
+
+| Feature | Human Mode | Agent Mode (`--agent`) |
+|---------|-----------|------------------------|
+| JSON Output | Pretty-printed (indented) | Compact (no spaces) |
+| List Output | JSON array | JSON Lines (NDJSON) |
+| Error Output | Friendly message to stderr | Structured JSON to stderr |
+| Exit Codes | 0, 1, or 2 | Semantic (0, 1, 2) |


The entire agent-mode.md document references a --agent flag that does not exist in the codebase. The actual behavior is that the default mode is already agent-compatible (compact JSON, NDJSON for lists), and -v/--verbose switches to human-friendly mode. This document should either be updated to reflect the actual implementation or the --agent flag should be implemented in the code.

Copilot · 2026-02-20T23:59:43Z

docs/agent-mode.md

+| JSON Output | Pretty-printed (indented) | Compact (no spaces) |
+| List Output | JSON array | JSON Lines (NDJSON) |
+| Error Output | Friendly message to stderr | Structured JSON to stderr |
+| Exit Codes | 0, 1, or 2 | Semantic (0, 1, 2) |


The comparison table states that "Human Mode" and "Agent Mode" have identical exit codes (0, 1, or 2) under different labels ("0, 1, or 2" vs "Semantic (0, 1, 2)"). These appear to be the same, making this distinction unclear and potentially confusing. Clarify what makes the exit codes "semantic" in agent mode if they're the same values.

Suggested change

| Exit Codes | 0, 1, or 2 | Semantic (0, 1, 2) |

| Exit Codes | 0, 1, or 2 | 0, 1, or 2 (with machine-readable JSON error bodies) |

In both modes, the numeric exit codes are the same; agent mode additionally guarantees that non-zero exits include a structured JSON error payload whose `code` field matches the semantics defined in the "Exit Codes" section above.

Copilot · 2026-02-20T23:59:43Z

README.md

+| URL Path | MCP Method |
+|---|---|
+| `/tools` | `tools/list` |
+| `/tools/<name>` | `tools/call` |
+| `/resources` | `resources/list` |
+| `/resources/<path>` | `resources/read` |
+| `/prompts` | `prompts/list` |
+| `/prompts/<name>` | `prompts/get` |


Minor inconsistency: The URL path description uses angle brackets in some places (/tools/<name>) which is a common convention, but consider clarifying that these are placeholders and showing an actual example alongside the pattern for better clarity.

Copilot · 2026-02-20T23:59:43Z

docs/mcp-servers.md

@@ -0,0 +1,64 @@
+# MCP Server Setup
+
+murl works with any MCP server that exposes an HTTP endpoint, including servers using the Streamable HTTP transport protocol.


The phrase "exposes an HTTP endpoint" could be more specific. Consider clarifying "exposes an HTTP JSON-RPC endpoint" for consistency with the rest of the documentation and to avoid ambiguity about what kind of HTTP endpoint is expected.

Copilot · 2026-02-20T23:59:43Z

README.md

+### OAuth

-Once mcp-proxy is running, you can use murl to interact with your stdio MCP server:
+murl supports OAuth 2.0 with Dynamic Client Registration (RFC 7591) and PKCE. Tokens are cached automatically.

 ```bash
-# List available tools
-murl http://localhost:3000/tools
+# First call triggers browser-based OAuth flow
+murl https://example.com/mcp/tools

-# Call a tool with arguments
-murl http://localhost:3000/tools/my_tool -d param1=value1 -d param2=value2
+# Skip auth for public servers
+murl https://example.com/mcp/tools --no-auth

-# List resources
-murl http://localhost:3000/resources
-
-# Get a prompt
-murl http://localhost:3000/prompts/my_prompt -d arg1=value
+# Force re-authentication
+murl https://example.com/mcp/tools --login
 ```


The OAuth section describes functionality that appears to be implemented (--no-auth and --login flags exist in murl/cli.py), but this section lacks context about when OAuth is needed. Consider adding a brief note about which MCP servers require authentication versus public servers that don't, to help users understand when to use these flags.

Copilot · 2026-02-20T23:59:43Z

README.md

+| `-v, --verbose` | Print request/response details to stderr |
+| `--agent` | Agent mode — compact JSON, NDJSON lists, structured errors |


The --agent flag does not exist in the codebase (murl/cli.py). The current implementation uses the default mode for compact JSON output (which matches the described "agent mode" behavior) and -v/--verbose for pretty-printed output (which matches "human mode" behavior). Either implement the --agent flag or update the documentation to reflect the actual behavior where the default is agent-compatible and -v provides human-friendly output.

Suggested change

| `-v, --verbose` | Print request/response details to stderr |

| `--agent` | Agent mode — compact JSON, NDJSON lists, structured errors |

| `-v, --verbose` | Pretty-print JSON for humans and print request/response details to stderr |

Copilot AI review requested due to automatic review settings February 20, 2026 23:54

Copilot started reviewing on behalf of turlockmike February 20, 2026 23:55 View session

turlockmike merged commit 702d773 into master Feb 20, 2026
7 checks passed

Copilot AI reviewed Feb 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Condense README, add Homebrew install#57

Condense README, add Homebrew install#57
turlockmike merged 1 commit intomasterfrom
docs/condense-readme

turlockmike commented Feb 20, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Copilot AI Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-| Exit Codes | 0, 1, or 2 | Semantic (0, 1, 2) |
+| Exit Codes | 0, 1, or 2 | 0, 1, or 2 (with machine-readable JSON error bodies) |
+In both modes, the numeric exit codes are the same; agent mode additionally guarantees that non-zero exits include a structured JSON error payload whose `code` field matches the semantics defined in the "Exit Codes" section above.

		@@ -0,0 +1,64 @@
		# MCP Server Setup

		murl works with any MCP server that exposes an HTTP endpoint, including servers using the Streamable HTTP transport protocol.

		\| `-v, --verbose` \| Print request/response details to stderr \|
		\| `--agent` \| Agent mode — compact JSON, NDJSON lists, structured errors \|

	\| `-v, --verbose` \| Print request/response details to stderr \|
	\| `--agent` \| Agent mode — compact JSON, NDJSON lists, structured errors \|
	\| `-v, --verbose` \| Pretty-print JSON for humans and print request/response details to stderr \|

Conversation

turlockmike commented Feb 20, 2026

Summary

Test plan

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants