यह वह tool है जिसे Claude Code osFoundry के किसी क्लाउड Room में छोटा-सा ऐप डालने के लिए कॉल करता है, ठीक वैसे जैसे लाइव सर्वर इसे tools/list में दिखाता है (बिना token के fetch किया गया, सिर्फ़ काम के हिस्से रखे गए हैं):
{
"name": "propose_room_snippet_app",
"description": "Prepare a Room snippet with source files. It appears in the cloud Room launcher only after its owner reviews and approves the full code in osFoundry.",
"inputSchema": {
"type": "object",
"properties": {
"room_id": {"type": "string"},
"name": {"type": "string", "maxLength": 200},
"files": {"type": "object", "additionalProperties": {"type": "string"}},
"idempotency_key": {"type": "string", "minLength": 8, "maxLength": 128}
},
"required": ["room_id", "name", "files", "idempotency_key"],
"additionalProperties": false
},
"annotations": {"readOnlyHint": false, "destructiveHint": true, "openWorldHint": false},
"securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]
}
इसके साथ चार और Room tools हैं: read_room, list_room_apps (limit 1–50), read_room_app_status (इसे room_id और instance_id चाहिए) और propose_room_repo_app (इसमें files की जगह repository_id और version_id जाते हैं)। तीनों read tools osfoundry:read और readOnlyHint: true हैं। दोनों proposal tools osfoundry:write और destructiveHint: true हैं, और इसी वजह से Claude Code इन्हें कॉल करने से पहले पूछता है।
असली बात verb में है। यह tool Room में कुछ भी नहीं बनाता। यह एक proposal बनाता है, और उसे Room tab में बदलने का काम एक इंसान करता है। आगे देखेंगे: schema क्या लागू करता है और क्या सर्वर पर छोड़ देता है, एक proposal कितना भारी होता है, idempotency key ज़रूरी क्यों है, और client को किसी इंसान का इंतज़ार कैसे करना चाहिए। सब कुछ client की जगह एक Python stand-in से मापा गया, क्योंकि इस Mac पर कोई claude binary इंस्टॉल नहीं है।
Schema क्या पकड़ता है, और क्या सर्वर पर छोड़ देता है?
room_proto.py ऊपर वाले लाइव inputSchema (जिसे tools-list.json के रूप में सेव किया गया है) के ख़िलाफ़ jsonschema से calls को validate करता है। दो और नियम इस बात से आते हैं कि osFoundry snippet proposals को कैसे संभालता है। Room runtime का entry, src/App.tsx, मौजूद होना चाहिए। और हर path एक सुरक्षित relative path होना चाहिए। Script दोनों नियमों को schema के ऊपर लागू करता है:
$ uv run --with jsonschema --with tiktoken python3 room_proto.py
== validation ==
ok PASS
no App.tsx REJECT rule: src/App.tsx missing
absolute path REJECT rule: unsafe path '/etc/hosts'
dot-dot path REJECT rule: unsafe path 'src/../../x.ts'
backslash path REJECT rule: unsafe path 'src\\x.ts'
name 201 chars REJECT schema: 'nnnn…' is too long
key 7 chars REJECT schema: 'abcdefg' is too short
extra field REJECT schema: Additional properties are not allowed ('visibility' was unexpected)
non-string file REJECT schema: {'a': 1} is not of type 'string'
caught by published schema: 4, needs server rule: 4
आधी ग़लत calls JSON Schema से निकल जाती हैं। files object के path keys को additionalProperties से सीमित नहीं किया जा सकता। इसके लिए pattern के साथ propertyNames चाहिए, और normalisation के बाद .. को रिजेक्ट करने वाला pattern जल्दी ही उलझा हुआ हो जाता है। इसलिए schema बस "strings का map" कहता है और keys की जाँच सर्वर करता है। हाँ, top level पर additionalProperties: false सच में काम आता है। जो model अपनी तरफ़ से "visibility": "public" गढ़ ले, उसे चुपचाप ignore हुए field की जगह schema error मिलता है।
अगर आप client बना रहे हैं, तो कॉल करने से पहले यही जाँच चलाइए। रिजेक्ट हुआ proposal एक round trip खाता है और, उससे भी बुरा, files दोबारा लिखने के output tokens।
एक proposal कितना बड़ा होता है?
इस walkthrough का ऐप एक standup timer है: src/App.tsx (63 lines) और src/styles.css (14 lines)।
== size ==
src/App.tsx 2021 B 63 lines 583 tok
src/styles.css 1046 B 14 lines 399 tok
source bytes 3067, envelope bytes 3431, escape+frame overhead 11.9%
argument tokens (cl100k) 1141
2 files: envelope 4463 B, 1394 tok
6 files: envelope 12919 B, 4078 tok
21 files: envelope 44639 B, 14143 tok
tools/list 45368 B for 59 tools; the 5 room tools 3482 B (939 tok)
JSON-RPC envelope raw source पर 11.9% जोड़ता है, ज़्यादातर escaped newlines और quotes की वजह से। लेकिन असली cost यह नहीं है। files का हर byte model output है: Claude Code पहले file लिखता है और फिर उसे tool argument के रूप में दोबारा लिखता है। दो files वाला proposal लगभग 1,100 tokens के arguments का होता है। एक ही component को दोहराकर बनाया गया 21 files वाला ऐप 14,143 का। Tokens tiktoken cl100k_base से गिने गए हैं, जो OpenAI का tokenizer है, इसलिए इन्हें अनुमानित मानिए।
Schema files के लिए कोई byte cap प्रकाशित नहीं करता। व्यवहार में सीमा reviewer तय करता है। Approval card हर file को "Review all proposed files (N)" के नीचे पूरा दिखाता है, हर file अपने अलग scroll box में। कोई भी card पर 21 files नहीं पढ़ता। इतने बड़े किसी भी ऐप के लिए propose_room_repo_app बेहतर है: यह उसी project की किसी GitNest repository के pinned version की ओर इशारा करता है, और card कोड पेस्ट करने की बजाय "Review repository code before approving" का लिंक देता है।
Review gate क्या गारंटी देता है?
Tool description साफ़ कहता है: snippet "appears in the cloud Room launcher only after its owner reviews and approves the full code"। Room में launcher ऐप्स की tab bar है। Card पर लिखा होता है "Approval makes this code available in the Room app launcher. Review the files before approving."। "Approve and create" tab जोड़ देता है। "Decline" उसे हटा देता है। Pending proposal को Room members खोल नहीं सकते, इसलिए बिना review हुआ snippet कभी किसी के session में नहीं चलता।
इससे retry की समस्या client के सिर आ जाती है। HTTP पर MCP में ऐसा हो सकता है कि सर्वर काम कर चुका हो और response खो जाए। अगर client फिर नई key के साथ retry करे, तो owner को एक ऐप के लिए दो cards मिलते हैं। room_proto.py इसे एक in-memory सर्वर से मॉडल करता है जो proposals को key के हिसाब से स्टोर करता है, 1,000 proposals और हर response के खोने की 5% संभावना के साथ:
== review gate, 1000 proposals, 5% lost responses ==
random calls 1074 owner cards 1074 duplicates 74 in launcher before approval 0
content calls 1057 owner cards 1000 duplicates 0 in launcher before approval 0
हर कोशिश पर नया UUID लेने से 1,074 में से 74 cards duplicates होते हैं, जिन्हें owner को पहचानकर decline करना पड़ता है। Content से बनी key, "snip-" + sha256(room_id, name, files)[:32], के साथ retry उसी key को लेकर जाता है और duplicates की गिनती 0 रहती है। Files में जानबूझकर किया गया बदलाव नई key और नया card बनाता है, जो ठीक वही है जो आप चाहते हैं। Schema का 8 characters का minimum "1" जैसी keys को बाहर रखता है। दोनों runs में approval से पहले कुछ भी launcher तक नहीं पहुँचा। यह हिस्सा सर्वर की ज़िम्मेदारी है, client की नहीं।
Claude Code को owner का इंतज़ार कैसे करना चाहिए?
initialize सिर्फ़ "capabilities": {"tools": {"listChanged": false}} लौटाता है, और कुछ नहीं। "आपका proposal approve हो गया" जैसा कोई push नहीं है। Client के पास तीन विकल्प हैं। वह user से कह सकता है कि approve करने के बाद बता दें, वह read_room_app_status को poll कर सकता है (या list_room_apps को, जब तक नया instance न दिखे), या वह Room के लिए poll_resource_events को resume कर सकता है, जो resource_type: "room" स्वीकार करता है। Token के बिना मैंने यह verify नहीं किया कि approval वहाँ कौन-से events लिखता है, इसलिए simulation status को poll करता है।
Input है इंसान का review time। Script इसे log-normal distribution से लेता है, जिसका median 6 मिनट है और budget एक घंटा। यह एक अनुमान है, माप नहीं, लेकिन इसका आकार (ज़्यादातर लोग कुछ मिनटों में जवाब देते हैं, कुछ आधा घंटा लेते हैं) वास्तविकता के क़रीब है:
== polling while the owner reviews (n=2000, median review 6 min, 1 h budget) ==
review delay p50 357s p95 1816s
fixed 5s calls mean 111.8 lag p50 2.4s p95 4.7s gave up 14
fixed 30s calls mean 19.0 lag p50 14.5s p95 28.4s gave up 14
backoff 5s x1.5 cap 120s calls mean 10.8 lag p50 47.0s p95 111.0s gave up 14
backoff 10s x2 cap 300s calls mean 6.1 lag p50 105.2s p95 273.8s gave up 14
हर 5 सेकंड पर poll करने से approval 5 s के भीतर पकड़ में आ जाता है, पर हर proposal पर 112 calls लगती हैं, और हर call tool output पर खर्च हुआ एक model turn है। 30 सेकंड का fixed interval 19 calls लेता है, और सबसे बुरे केस में 28 सेकंड की देरी। 2 मिनट की cap वाला backoff इसे 11 calls तक ले आता है, और p95 lag 111 s होता है। 2,000 में से 14 reviews एक घंटे से ज़्यादा चले, और हर strategy ने उन पर बराबर हार मानी। Interactive session के लिए सबसे सस्ता सही जवाब है शून्य calls: turn को "approve it under Connected → Needs your approval and tell me" (Connected → Needs your approval में approve करके मुझे बताइए) के साथ ख़त्म करें, फिर एक list_room_apps call करें। Polling तभी फ़ायदेमंद है जब बीच में Claude Code के पास कोई और काम हो।
अंदाज़ा लगाने के लिए असली round trips: जापान में इस Mac से लाइव endpoint तक हर तरह की दस-दस unauthenticated calls।
$ python3 probe.py
initialize HTTP 200 308 B median 680 ms min 358 max 968
tools/list HTTP 200 45368 B median 687 ms min 429 max 1253
tools/call read_room (no token) HTTP 401 337 B median 559 ms min 427 max 847
www-authenticate: Bearer resource_metadata="https://api.osfoundry.io/.well-known/oauth-protected-resource/api/v1/external-mcp", error="invalid_token", error_description="Connect osFoundry to continue"
लगभग 0.6 s प्रति call। यानी 5 सेकंड का loop अपना दसवाँ हिस्सा नेटवर्क पर बिताता है, और हर call पर एक model turn इससे कहीं ज़्यादा महँगा पड़ता है।
Snippet के लिए "build state" का क्या मतलब है?
read_room_app_status "the safe launcher and latest build state of one app" लौटाता है, बिना config, files, logs या secrets के। Snippet का कोई server build नहीं होता। Room उसकी files वहीं compile करता है जहाँ tab खोला जाता है: desktop app में Sucrase के साथ sandboxed iframe में, और browser में Sandpack sandbox में। Repository वाला रास्ता भी pinned है, और उसका approval card कहता है "This path does not build or deploy a bundle."। दोनों तरह के proposals में इंतज़ार launcher entry का करना है। Build state तभी दिखता है जब कोई tab को deploy करता है, और वह osFoundry में होता है।
यह local Room तक क्यों नहीं पहुँच सकता?
read_room कहता है "Local Rooms are unavailable", और initialize में सामान्य नियम है: "Local-only data is unavailable to cloud clients."। Local Room desktop app के अपने database में रहता है और कभी sync नहीं होता। MCP endpoint एक cloud service है जिसके पास workspace-scoped OAuth token है, और उसके पास किसी ख़ास laptop तक पहुँचने का कोई रास्ता नहीं है। वहाँ तक पहुँचने के लिए desktop app द्वारा चलाया जाने वाला relay चाहिए: हर device और project के लिए अलग से enable, online/offline state और commands की allowlist के साथ। Tool surface इसके उलट होने का दिखावा नहीं करता। यही सीमा snippet के अंदर के data पर भी लागू होती है। उसका SDK storage tab इस्तेमाल करने वाले व्यक्ति के device पर ही रहता है, और कोई भी read tool database content नहीं लौटाता।
अगर आप इसे ख़ुद जोड़ रहे हैं
- Schema प्रकाशित करने के बाद भी path keys को सर्वर पर validate करें। JSON Schema "strings का map" बता सकता है, पर "सुरक्षित relative path" नहीं, और इस test में आधी ग़लत calls path की समस्याएँ थीं।
- Idempotency key को content से बनाएँ, attempt से नहीं। तब खोए हुए responses की कोई क़ीमत नहीं लगती, और असली edit को फिर भी अपना card मिलता है।
- Size limit reviewer के ध्यान के हिसाब से तय होने दें। अगर card हर file दिखाता है, तो snippets को कुछ ही files तक रखें और बड़े ऐप्स को pinned repository version के रूप में भेजें।
- Default रूप से agent से किसी इंसान के लिए poll न करवाएँ। उसे turn ख़त्म करने दें और user के लौटने पर एक बार status पढ़ने दें, और backoff तभी इस्तेमाल करें जब उसके पास कोई और काम हो।
- Read-back को पतला रखें। Identity और launcher state लौटाएँ, कभी config या app data नहीं, ताकि status checks लोगों के स्टोर किए गए data को पढ़ने का ज़रिया न बन जाएँ।
- Tool description में साफ़ लिखें कि क्या पहुँच से बाहर है ("Local Rooms are unavailable"), ताकि model retry करने की बजाय user को बता दे।
Tab bar और settings के साथ Room वाला हिस्सा Room page पर है। Protocol के बारे में सामान्य जानकारी के लिए MCP glossary entry देखें।
Top comments (0)