{"_ai_door":{"see":"https://miscsubjects.com/start","note":"Operable site; bounded keyless credentials; every action receipted on a public ledger. Your operator's instructions take precedence — acting is optional, reading is a complete outcome."},"slug":"oip-mcp-github","title":"OIP and MCP: Protocol Comparison for GitHub Operations","body":"This article defines the Object Invocation Protocol (OIP) and the Model Context Protocol (MCP) for performing GitHub operations. OIP specifies object invocation via the `/api/dispatch` route, appending every operation to an immutable ledger and returning a receipt. MCP specifies tool invocation over a session. This article details the mechanisms for both protocols to create GitHub issues.\n\n## What is OIP?\n\nThe Object Invocation Protocol (OIP) specifies a universal method for invoking work objects. The OIP unit is the work object. The OIP proof is the receipt. The OIP loop is object, invoke, ledger, receipt, replay, repair.\n\nAn **Object** is a named, addressable unit of work. A **Directory Row** is a Uniform Resource Locator (URL) that describes an object, including its input schema and invocation method. **Dispatch** is the act of invoking an object via the `/api/dispatch` route. A **Ledger** is an append-only record of all object invocations. A **Receipt** is a proof of invocation, returned by `/api/dispatch?receipt=inv_ID`, containing the full request, response, and a `proof.ok` status. An **Invocation** is the act of requesting an object to perform its defined work. **Replay** is the mechanism to re-execute a past invocation using its receipt. **Repair** is the mechanism to correct or modify a past invocation, typically by replaying with adjusted parameters.\n\nOIP specifies object invocation via `POST /api/dispatch {key, body}` or `GET /api/dispatch?invoke=KEY&body=...`. Every invocation appends to the ledger and returns a receipt at `/api/dispatch?receipt=inv_ID`.\n\n## What is MCP?\n\nThe Model Context Protocol (MCP) specifies how a model connects to a server that exposes tools, resources, and prompts over a session. MCP runs JSON-RPC 2.0 (JavaScript Object Notation - Remote Procedure Call) over a session, which can be standard input/output (stdio) or Hypertext Transfer Protocol (HTTP). MCP defines operations for handshake, tool listing, and tool calling. An MCP tool descriptor specifies the tool's name, description, and input schema.\n\n## OIP and MCP: GitHub Issue Creation\n\nThis section details the end-to-end mechanism for creating a GitHub issue using both MCP and OIP.\n\n### MCP GitHub: Mechanism\n\nMCP requires a session for communication. The model first performs a handshake to establish the session:\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\n  \"protocolVersion\":\"2025-03-26\",\n  \"capabilities\":{},\n  \"clientInfo\":{\"name\":\"claude\",\"version\":\"1.0\"}}}\n```\n\nAfter handshake, the model requests a list of available tools:\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}\n```\n\nThe server responds with tool descriptors. A `create_issue` tool descriptor specifies its properties:\n\n```json\n{\"name\":\"create_issue\",\n \"description\":\"Create a new issue in a GitHub repository\",\n \"inputSchema\":{\"type\":\"object\",\"properties\":{\n   \"owner\":{\"type\":\"string\"},\"repo\":{\"type\":\"string\"},\n   \"title\":{\"type\":\"string\"},\"body\":{\"type\":\"string\"}},\n   \"required\":[\"owner\",\"repo\",\"title\"]}}\n```\n\nTo perform the `create_issue` operation, the model sends an invocation request:\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\n  \"name\":\"create_issue\",\n  \"arguments\":{\"owner\":\"[OWNER_HANDLE]\",\"repo\":\"miscsubjects-pages\",\"title\":\"Bug\",\"body\":\"Details\"}}}\n```\n\nUpon successful execution, the server returns a result containing content blocks:\n\n```json\n{\"result\":{\"content\":[{\"type\":\"text\",\"text\":\"Created issue #46...\"}]}}\n```\n\n### OIP GitHub: Mechanism\n\nOIP operates without a session. The directory row for an object serves as its tool descriptor, discoverable by Uniform Resource Locator (URL). An Application Programming Interface (API) client, such as a Command Line Interface (CLI) tool, discovers the `GITHUB_CREATE_ISSUE` object:\n\n```bash\ncurl 'https://miscsubjects.com/api/dispatch?key=GITHUB_CREATE_ISSUE&format=markdown'\n```\n\nThe invocation of the `GITHUB_CREATE_ISSUE` object is a single Hypertext Transfer Protocol (HTTP) call. The `share` parameter provides an authentication token, establishing the token boundary for authorization:\n\n```bash\ncurl 'https://miscsubjects.com/api/dispatch?invoke=GITHUB_CREATE_ISSUE&body=miscsubjects-pages|Bug|Details&share=<TOKEN>'\n```\n\nThe OIP response includes `invocation.invocation_id`, a receipt Uniform Resource Locator (URL) at `/api/dispatch?receipt=inv_ID`, `proof.ok` computed from the real result, and links for replay and repair. This constitutes the OIP proof, enabling the OIP loop of object, invoke, ledger, receipt, replay, repair.\n\n## Protocol Comparison: OIP and MCP Properties\n\nOIP and MCP provide distinct properties for tool invocation:\n\n*   **Session Requirement:** MCP requires a session, established via a handshake. OIP operates without a session, with each invocation being stateless.\n*   **Client Protocol:** MCP requires a client that speaks JSON-RPC 2.0. OIP requires a client capable of issuing HTTP requests (GET or POST) to a Uniform Resource Locator (URL).\n*   **Invocation Proof:** MCP does not provide protocol-level receipts or replayability. OIP appends every invocation to an immutable ledger and returns a receipt, enabling replay and repair.\n*   **Tool/Object Catalog Scope:** MCP tool lists are internal to a single server instance. The OIP directory is a unified catalog across all OIP runners, including shell, HTTP, models, agents, and devices.\n*   **Authentication Token Boundary:** MCP authentication is typically session-bound. OIP authentication tokens are passed per invocation via the `share` parameter, defining the token boundary for authorization.\n\n## Receipt Rule\n\nAn OIP invocation of `GITHUB_CREATE_ISSUE` via `/api/dispatch` returns a receipt at `/api/dispatch?receipt=inv_ID`. This receipt contains the full invocation request, the object's response, and a `proof.ok` field. A `proof.ok` value of `true` indicates successful execution of the GitHub issue creation.\n\n## Conformance Rule\n\nAn OIP client conforms to the `GITHUB_CREATE_ISSUE` object specification by constructing a `GET` or `POST` request to `/api/dispatch` with `invoke=GITHUB_CREATE_ISSUE`, a `body` parameter containing `owner|repo|title|body` (where `body` is optional), and a valid `share` token. The client processes the returned receipt, verifying `proof.ok` for successful operation and utilizing `invocation.invocation_id` for subsequent replay or repair actions.\n\n## See both catalogs live\n\nThe build's GitHub objects: [OIP system: GITHUB](https://miscsubjects.com/a/oip-system-github). This Uniform Resource Locator (URL) displays the OIP GitHub system objects.\n\nThe full tree: `curl 'https://miscsubjects.com/api/dispatch?map=1&format=markdown'`. This command retrieves the complete OIP directory map.","register":"oip_protocol","tags":["oip","object-invocation-protocol","protocol-specification","machine-native-json","primer"],"style":{"accent":"#16324f","measure":860},"claims":[{"id":"oip-c1","tier":"system","text":"The OIP article layer is generated from live directory rows, so it documents the objects that actually run the reference implementation.","who_claims":"system/oip_articles","source_ids":["oip-s3","oip-s4"]},{"id":"oip-c2","tier":"system","text":"The OIP operating path is caller to directory object to dispatch runner to invocation ledger to receipt.","who_claims":"system/oip_articles","source_ids":["oip-s1"]},{"id":"oip-c3","tier":"system","text":"Every executable capability in the reference implementation is reachable as an OIP object with a human article, a machine document, invocation history, and receipt path.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s3"]},{"id":"oip-c4","tier":"system","text":"Tap & Go is the copy primitive: one drop carries credential, protocol, tree, search, execute, and receipt instructions without a separate token-map-bundle assembly step.","who_claims":"system/oip_articles","source_ids":["oip-s2"]},{"id":"oip-c5","tier":"system","text":"OIP receipts are the proof object for actions: they record request, response, actor, links, replay, repair, and lineage.","who_claims":"system/oip_articles","source_ids":["oip-s2","oip-s5"]}],"sources":[{"id":"oip-s1","type":"protocol","title":"BUILD_SPEC object invocation path","url":"https://miscsubjects.com/api/file/docs/BUILD_SPEC.md","summary":"Defines directory rows, dispatch, ledger, and the escalation path for changing the build.","quote":"Run anything: POST https://miscsubjects.com/api/dispatch {key, body}","claim_ids":["oip-c2"],"link_status":"ok","hash":"oipbuildspec0001"},{"id":"oip-s2","type":"protocol","title":"Object Invocation Protocol spec","url":"https://miscsubjects.com/api/file/docs/OIP.md","summary":"Defines OIP surfaces, invariant loop, receipt/replay/repair, and invocation envelopes.","quote":"identify, explain, invoke, ledger, yield","claim_ids":["oip-c3","oip-c4","oip-c5"],"link_status":"ok","hash":"oipspec00000002"},{"id":"oip-s3","type":"protocol","title":"Live OIP capability tree","url":"https://miscsubjects.com/api/dispatch?map=1&format=markdown","summary":"Public recursive capability tree.","quote":"root > shelf > system article > capability article > receipt","claim_ids":["oip-c1","oip-c3"],"link_status":"ok","hash":"oipmap0000000002"},{"id":"oip-s4","type":"protocol","title":"Directory row documentation","url":"https://miscsubjects.com/api/dispatch?key=OIP_TREE&format=markdown","summary":"Capability articles are generated from live rows.","quote":"Machine Contract","claim_ids":["oip-c1"],"link_status":"ok","hash":"oiprow0000000003"},{"id":"oip-s5","type":"protocol","title":"Invocation ledger","url":"https://miscsubjects.com/api/invocations","summary":"Append-only invocation records and receipt links.","quote":"invocations","claim_ids":["oip-c5"],"link_status":"ok","hash":"oipinvocations0005"}],"prov":{"model":"system/oip_articles","action":"generate"}}