docs: publish translated docs in twelve languages and the tool that maintains them (#3280)

This commit is contained in:
Max 2026-08-14 17:07:34 +01:00 • committed by GitHub
commit 52ad0a8876
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 89737 additions and 54 deletions

View file

@ -0,0 +1,134 @@
---
translation:
sections: [b50152f05c81e786, b302059b22fb7cb4, 85682a1bf561243a, 53fc48838eb6837a, b24190e0842786ec, 85f93e150fc9b240]
tool: 1
---
# Context {#the-context}
tool के arguments model से आते हैं। बाकी सब कुछ (जिस request को आप serve कर रहे हैं, जिस server में आप हैं, client से वापस बात करने का तरीका) एक ही object से आता है: **`Context`**।
न आपको इसे बनाना है, न configure करना है। बस माँगना है।
## इसे माँगें {#ask-for-it}
किसी भी tool में `Context` से annotate किया गया parameter जोड़ें:
```python title="server.py" hl_lines="2 8"
--8<-- "docs_src/context/tutorial001.py"
```
* SDK हर request के लिए नया `Context` बनाता है और उसे pass करता है।
* parameter का **नाम मायने नहीं रखता**। `ctx`, `context`, `c`: SDK इसे annotation से पहचानता है।
* resources और prompts भी इसी तरह एक declare कर सकते हैं।
* `ctx.request_id` उस request की id है जिसे आपका function अभी serve कर रहा है।
!!! info
अगर आपने FastAPI इस्तेमाल किया है, तो यह तरीका आपने देखा है: framework के अपने type
(वहाँ `Request`, यहाँ `Context`) वाला parameter declare करें और framework उसे दे देता है। कुछ register नहीं करना, कुछ
configure नहीं करना: type annotation ही पूरा mechanism है।
### model को नहीं दिखता {#invisible-to-the-model}
यही बात अच्छे से समझ लेने की है। यह रहा वह input schema जो `tools/list` `search_books` के लिए बताता है:
```json
{
"type": "object",
"properties": {
"query": {"title": "Query", "type": "string"}
},
"required": ["query"],
"title": "search_booksArguments"
}
```
एक ही property। `ctx` कोई argument नहीं है: यह schema में कभी नहीं आता, model को इसके बारे में कभी नहीं बताया जाता, और कोई client इसे भर नहीं सकता। यह आपके और SDK के बीच का समझौता है, wire पर नहीं दिखता।
### इसे आज़माएँ {#try-it}
MCP Inspector के साथ server चलाएँ:
```console
uv run mcp dev server.py
```
`search_books` के form में सिर्फ़ एक `query` field है। इसे `dune` के साथ call करें:
```text
[request 3] Found 3 books matching 'dune'.
```
संख्या वही है जो यह request संयोग से थी। tool को दोबारा call करें और यह बदल जाती है: हर request को अपना `Context` मिलता है।
## यह आपको क्या देता है {#what-it-gives-you}
inject किया गया object छोटा है। `request_id` के अलावा:
* `await ctx.read_resource(uri)`: tool के अंदर से server का **अपना** resource पढ़ें। अगला section।
* `await ctx.report_progress(progress, total, message)`: लंबे call के दौरान caller को progress भेजते रहें। पूरी जानकारी **[Progress](progress.md)** में है।
* `await ctx.elicit(message, schema)` और `await ctx.elicit_url(...)`: tool को रोककर user से सवाल पूछें। यह **[Elicitation](elicitation.md)** है।
* `ctx.session`: इस client के साथ बातचीत का server वाला पक्ष। client को भेजे जाने वाले notifications यहीं रहते हैं; आखिरी section इसका इस्तेमाल करता है।
* `ctx.headers`: transport जो request headers लाया, या stdio पर `None`। custom header `(ctx.headers or {}).get("x-...")` से पढ़ें। headers client का दिया हुआ input हैं - locale या feature flag के लिए ठीक, identity के लिए कभी नहीं।
* `ctx.request_context`: हर request का raw record। जिस field की ज़रूरत पड़ेगी वह है `lifespan_context`, वह object जो आपके startup code ने yield किया था (**[Lifespan](lifespan.md)** देखें)।
logging जानबूझकर इस सूची में नहीं है। server Python के `logging` module से log करता है, किसी भी दूसरे Python program की तरह। **[Logging](logging.md)** वह छोटा page है जो बताता है क्यों।
!!! tip
injection सिर्फ़ उसी function के लिए होता है जिसे आपने register किया। आपका tool जिस helper को call करता है, उसे
अपना `Context` नहीं मिलता; `ctx` को साधारण argument की तरह नीचे pass करें। कहीं और से लाने के लिए कोई ambient
"current context" नहीं है।
## अपने resources पढ़ें {#read-your-own-resources}
server के resources सिर्फ़ clients के लिए नहीं हैं। tool भी उन्हें पढ़ सकता है:
```python title="server.py" hl_lines="16"
--8<-- "docs_src/context/tutorial002.py"
```
`ctx.read_resource` URI को उसी registry से resolve करता है जो `resources/read` को serve करती है, इसलिए tool को वही मिलता है जो client को मिलता: `ReadResourceContents` का iterable, हर content block के लिए एक। इस URI के लिए एक है:
```python
contents.content # 'fiction, non-fiction, poetry'
contents.mime_type # 'text/plain'
```
* `content` ठीक वही है जो `genres()` ने लौटाया। सच का एक ही स्रोत: client resource को browse करता है, आपके tools उसे इस्तेमाल करते हैं, कोई string की copy नहीं बनाता।
* `describe_catalog` का इकलौता parameter `Context` है, इसलिए इसके input schema में **कोई property ही नहीं** है। model इसे `{}` के साथ call करता है।
## client को बताएँ कि सूची बदल गई {#tell-the-client-the-list-changed}
server जो देता है वह import time पर तय नहीं है। runtime पर tool register करें, फिर client को बताएँ:
```python title="server.py" hl_lines="15-16"
--8<-- "docs_src/context/tutorial003.py"
```
* `mcp.add_tool(recommend_book)` एक साधारण function को tool की तरह register करता है: name, description और schema ठीक वैसे ही निकाले जाते हैं जैसे `@mcp.tool()` निकालता।
* `await ctx.session.send_tool_list_changed()` `notifications/tools/list_changed` भेजता है। जिस client को यह मिलता है वह `tools/list` दोबारा call करता है और `recommend_book` देखता है।
इसके साथी हैं `send_resource_list_changed()`, `send_prompt_list_changed()`, और किसी एक खास resource में बदलाव के लिए `send_resource_updated(uri)`।
2026-07-28 connection पर clients को change notifications सिर्फ़ उस `subscriptions/listen` stream पर मिलते हैं जो उन्होंने खोला, इसलिए ऊपर के `send_*` methods उन streams तक नहीं पहुँचते। `Context` के publish methods हर subscribed stream पर एक साथ deliver करते हैं: `await ctx.notify_tools_changed()`, `await ctx.notify_prompts_changed()`, `await ctx.notify_resources_changed()`, और `await ctx.notify_resource_updated(uri)`। पूरी जानकारी, replicas पर scale out करने समेत, **[Subscriptions](subscriptions.md)** में है।
!!! check
जब तक कोई `enable_recommendations` नहीं चलाता, जिस tool का आप वादा कर रहे हैं वह मौजूद नहीं है। फिर भी उसे call
करें और नतीजा एक error है जिसे model पढ़ सकता है:
```text
Unknown tool: recommend_book
```
`enable_recommendations` चलाएँ, और ठीक वही call सफल हो जाता है। tool की सूची सच में
dynamic है: `tools/list` वही दिखाता है जो **अभी** register है।
## सारांश {#recap}
* किसी parameter को `Context` से annotate करें (tool, resource या prompt में) और SDK उसे inject कर देता है। नाम आपकी मर्ज़ी का।
* यह model को नहीं दिखता: input schema में हमेशा सिर्फ़ आपके असली arguments होते हैं।
* `ctx.request_id` request की पहचान है; `ctx.request_context.lifespan_context` वह है जो आपके startup ने yield किया।
* `await ctx.read_resource(uri)` से tool server के अपने resources पढ़ सकता है।
* `ctx.session` client तक वापस जाने का channel है: `send_tool_list_changed()` और उसके साथी उसे बताते हैं कि बदली गई सूची दोबारा fetch करे।
* progress reporting और elicitation भी `Context` से शुरू होते हैं; दोनों का अपना page है।
जो parameters model कभी नहीं देखता, और जिन्हें आपके अपने functions भरते हैं, वे **[Dependencies](dependencies.md)** हैं।

View file

@ -0,0 +1,163 @@
---
translation:
sections: [b0389403e98d25ad, e2cf58b43b285e86, a363e1a38e1a5971, 6cfac078feb18013, b4535bd61df337e6, e97ed44207f929fd]
tool: 1
---
# Dependencies {#dependencies}
tool के arguments model से आते हैं। कुछ values कभी वहाँ से नहीं आनी चाहिए: आपके records से निकाली गई कीमत, ऐसी confirmation जो सिर्फ़ कोई इंसान दे सकता है, कोई भी ऐसी चीज़ जिसे model गढ़कर गलत कर सकता है।
**Dependencies** वे parameters हैं जिन्हें आपके अपने functions भरते हैं। आप parameter को annotate करते हैं, function का नाम देते हैं, और tool चलने से पहले SDK उसे call करता है।
## एक declare करें {#declare-one}
parameter के type को `Annotated[...]` में लपेटें और `Resolve(fn)` जोड़ें:
```python title="server.py" hl_lines="18-19 23"
--8<-- "docs_src/dependencies/tutorial001.py"
```
* `check_stock` **resolver** है: सादा function, जिसे SDK `reserve_book` से पहले चलाता है और जिसकी return value `stock` argument बन जाती है।
* इसका `title` parameter tool का अपना `title` argument ही है, जिसका मिलान **नाम से** होता है। resolver को ठीक वही validated value दिखती है जो tool body को दिखेगी।
* tool body ऐसे `Stock` से शुरू होती है जो पहले से मौजूद है। tool में कोई lookup code नहीं, कोई "अगर यह न मिले तो" वाली भूमिका नहीं।
!!! info
अगर आपने FastAPI इस्तेमाल किया है, तो यह `Depends` है। वही तरीका, वही वजह: function बताता है
कि उसे क्या चाहिए, framework वह देता है, और सारी wiring type annotation में रहती है।
### model को नहीं दिखता {#invisible-to-the-model}
यह रहा वह input schema जो `tools/list` `reserve_book` के लिए बताता है:
```json
{
"type": "object",
"properties": {
"title": {"title": "Title", "type": "string"}
},
"required": ["title"],
"title": "reserve_bookArguments"
}
```
एक ही property। **[Context](context.md)** के `Context` की तरह, resolve किया गया parameter आपके और SDK के बीच का अनुबंध है: `stock` schema में नहीं है, model को इसके बारे में कभी नहीं बताया जाता, और जो client फिर भी `stock` value भेजता है उसे अनदेखा कर दिया जाता है। resolver की value ही वह अकेली value है जो आपके tool को मिल सकती है।
आखिरी बात ही असली बात है। जो parameter model दे ही नहीं सकता, उसे model गलत भी नहीं कर सकता।
### इसे आज़माएँ {#try-it}
server को MCP Inspector के साथ चलाएँ:
```console
uv run mcp dev server.py
```
`reserve_book` के form में सिर्फ़ एक `title` field है। `stock` उस पर कहीं नहीं है। इसे `Dune` के साथ call करें:
```text
Reserved 'Dune' (6 copies left).
```
tool body ने खुद कुछ भी नहीं खोजा: पहले `check_stock` चला, और उसका लौटाया `Stock` argument बनकर आया। `Neuromancer` आज़माएँ और वही resolver tool को शून्य थमा देता है।
!!! tip
आप tool body में सीधे `check_stock(title)` call भी कर सकते हैं। इसे dependency तब declare करें
जब value एक helper call से ज़्यादा की हकदार हो: stock की ज़रूरत वाला हर tool वही parameter
declare करता है, और चाहे कितने भी tools इसे declare करें, SDK resolver को प्रति call ज़्यादा से
ज़्यादा एक बार चलाता है। अगले sections बाकी जोड़ते हैं: एक-दूसरे पर निर्भर resolvers, और user से
पूछने वाले resolvers।
## Dependencies की dependencies {#dependencies-of-dependencies}
resolver उसी annotation से अपनी खुद की dependencies declare कर सकता है:
```python title="server.py" hl_lines="22 29-30"
--8<-- "docs_src/dependencies/tutorial002.py"
```
* `estimate_delivery` `check_stock` पर निर्भर है। SDK graph को क्रम से चलाता है: पहले stock, फिर estimate, फिर tool।
* `stock` और `delivery` दोनों को आखिरकार `check_stock` चाहिए, लेकिन यह **प्रति call एक बार** चलता है। एक inventory lookup, दो consumers।
* register करने को कुछ नहीं है। annotations ही graph **हैं**।
!!! check
"प्रति call एक बार" पर आँख मूँदकर भरोसा न करें। `check_stock` में एक `print` डालें और Inspector से
`order_book` call करें: प्रति call एक line। दो consumers, एक lookup।
SDK graph का विश्लेषण तब करता है जब tool register होता है, न कि जब उसे call किया जाता है। ऐसा parameter जिसे वह वर्गीकृत न कर सके - न `Context`, न `Resolve(...)`, न किसी tool argument का नाम - और resolvers का कोई cycle, दोनों startup पर `InvalidSignature` raise करते हैं। server किसी भी client के जुड़ने से पहले ही fail हो जाता है, और error में गड़बड़ी वाले parameter या resolver का नाम होता है।
resolver के parameters ठीक tool के parameters की तरह resolve होते हैं: कोई और `Resolve(...)`, नाम से tool के अपने arguments, या `Context` - `ctx.headers`, lifespan object, सब कुछ।
!!! warning
HTTP transports पर `Context` में `ctx.headers` शामिल होते हैं। headers **client का भेजा हुआ input** हैं,
किसी भी tool argument की तरह: locale या feature flag के लिए ठीक, पहचान के लिए कभी नहीं। caller कौन
है, यह आपकी authorization layer (**[Authorization](../run/authorization.md)**) से आता है, किसी ऐसे header से नहीं जिसे कोई भी set कर सकता है।
!!! tip
**प्रति call एक बार** का मतलब ठीक यही है: अगला `tools/call` `check_stock` को फिर से चलाता है। ऐसा resource
जिसे एक request से ज़्यादा जीना चाहिए - database pool, HTTP client - उसकी जगह **[Lifespan](lifespan.md)** में है, और
resolver उस तक `ctx.request_context.lifespan_context` के ज़रिए पहुँच सकता है।
## तभी पूछें जब ज़रूरी हो {#ask-when-you-must}
resolver को जवाब पता हो, यह ज़रूरी नहीं। वह `Elicit(message, Model)` लौटा सकता है और SDK user से पूछ लेता है - यानी **[Elicitation](elicitation.md)** की machinery, जो आपके लिए चलाई जाती है:
```python title="server.py" hl_lines="26-32 39"
--8<-- "docs_src/dependencies/tutorial003.py"
```
* stock में हो: `confirm_backorder` सीधे `Backorder` लौटाता है। **कोई सवाल नहीं, कोई round-trip नहीं।** user को तभी टोका जाता है जब उसका जवाब मायने रखता हो।
* stock में न हो: SDK elicitation भेजता है, जवाब को `Backorder` के हिसाब से validate करता है, और उसे inject कर देता है। आपका resolver protocol को कभी छूता तक नहीं।
* tool `backorder.confirm` को किसी भी दूसरे argument की तरह पढ़ता है। **नहीं** कहना भी एक जवाब है: elicitation `confirm=False` के साथ accept होता है, tool चलता है, और कोई order नहीं दिया जाता। पूछना tool body की plumbing नहीं, एक precondition बन गया।
और अगर user जवाब ही न दे - सवाल decline कर दे, या cancel कर दे?
!!! check
`Neuromancer` के लिए `order_book` चलाएँ और सवाल decline करें। annotation
`Annotated[Backorder, Resolve(...)]` के रूप में लिखी हो तो tool body कभी नहीं चलती; call ऐसे error
result के साथ fail होता है जिसे model पढ़ सकता है:
```text
Error executing tool order_book: Resolver for parameter 'backorder' could not resolve: elicitation was decline
```
precondition के लिए यही सही default है: जवाब नहीं, तो order नहीं। जब decline होना ऐसा नतीजा हो जिसे आपका tool खुद संभालना चाहे - backorder छोड़ दे पर फिर भी कोई दूसरा title सुझाए - तो इसके बजाय `ElicitationResult[Backorder]` annotate करें और tool को पूरा accept/decline/cancel नतीजा मिलता है जिस पर वह branch कर सके। **[Elicitation](elicitation.md)** वह रूप दिखाता है, और पूछने के बारे में बाकी सब भी: schema के नियम, तीनों जवाब, बातचीत का client वाला पक्ष।
!!! info
framework सवाल का transport negotiate हुए protocol version से चुनता है; ऊपर का code दोनों पर एक जैसा
है। **2026-07-28** और उसके बाद सवाल एक multi-round-trip `tools/call` के भीतर जाता है - server उसे
लौटाता है, client का `elicitation_callback` उसका जवाब देता है, और `Client` आपके लिए call को फिर से
आज़माता है (**[Multi-round-trip requests](multi-round-trip.md)**)। **2025-11-25** और उससे पहले यह call के
बीच में एक synchronous elicitation request होती है। हर सवाल प्रति call ठीक एक बार पूछा जाता है - यह
गारंटी सवाल के बारे में है, resolver के बारे में नहीं। multi-round-trip रूप में, जब भी call किसी सवाल के
बाद फिर से शुरू होता है, कोई भी resolver दोबारा चल सकता है, इसलिए `return Elicit(...)` से पहले का code
उन हर rounds पर चलता है; फिर दर्ज किया गया जवाब दोहराए गए सवाल को user से दोबारा पूछे बिना पूरा कर
देता है। दर्ज जवाब सिर्फ़ तभी देखा जाता है जब resolver पूछता है; जो resolver पूछे **बिना** जवाब दे देता
है, जैसे `check_stock`, वह हमेशा अपनी खुद की गणना की गई value देता है। चूँकि हर जवाब वापस उसके सवाल
से मिलाया जाता है, elicit करने वाले resolver को अपना सवाल tool के arguments और पहले के जवाबों से
deterministic ढंग से बनाना होगा। प्रति call बनने वाली value (`default_factory` id, timestamp) हर round
पर फिर से बनती है और ऐसे सवाल में नहीं आनी चाहिए जिससे जवाब को बँधना है। ऐसे अस्थिर data से बना सवाल
हर दर्ज जवाब को बासी दिखा देता है, इसलिए server उसे हर round पर फिर से पूछता है, जब तक client की
round limit call को खत्म नहीं कर देती।
## user से नहीं, client से पूछें {#ask-the-client-not-the-user}
Elicitation उन तीन सवालों में से एक है जो resolver पूछ सकता है, और multi-round-trip flow इनके अलावा कोई और सवाल नहीं होने देता। बाकी दो user के बजाय **client** के पास जाते हैं: client के ज़रिए LLM call चलाने के लिए `Sample(...)` लौटाएँ (एक `sampling/createMessage` request), या client के मौजूदा roots लाने के लिए `ListRoots()`। दोनों में से किसी का accept/decline नतीजा नहीं होता; consumer सीधे result type annotate करता है, `CreateMessageResult` (जब request में `tools` या `tool_choice` हो तो `CreateMessageResultWithTools`) या `ListRootsResult`:
```python title="server.py" hl_lines="10-15 21"
--8<-- "docs_src/dependencies/tutorial004.py"
```
* framework इन्हें ठीक `Elicit` की तरह route करता है: **2026-07-28** पर multi-round-trip `tools/call` के भीतर, **2025-11-25** पर standalone server->client request के ज़रिए। declare न की गई capability call को `-32021` protocol error के साथ मना कर देती है (`sampling`, `roots`, form-mode `elicitation`; जब request में `tools` या `tool_choice` हो तो `sampling.tools`)।
* ऊपर वाला info box सवालों के बारे में जो कुछ कहता है, वह बिना बदलाव लागू होता है: `Sample` request का मिलान उसके दर्ज result से उसके हूबहू rendering से होता है, इसलिए उसे tool के arguments और पहले के जवाबों से deterministic ढंग से बनाएँ; तब client LLM call की कीमत प्रति tool call एक बार चुकाता है, प्रति round एक बार नहीं। दर्ज result बाकी call भर `request_state` में साथ चलता है, इसलिए बहुत बड़ा completion बचे हुए हर round-trip को भारी बना देता है।
* standalone sampling और roots **features** 2026-07-28 पर deprecated हैं (SEP-2577)। जिन नए servers को client के model की ज़रूरत है वे इसी carrier के ज़रिए पूछते हैं; जिन्हें नहीं है उन्हें सीधे किसी LLM provider से integrate करना चाहिए। `"none"` के अलावा `include_context` की values खुद deprecated हैं; उनसे बचें।
## सारांश {#recap}
* tool parameter पर `Annotated[T, Resolve(fn)]`: SDK `fn` चलाता है और उसकी return value inject करता है।
* resolve किया गया parameter model को नहीं दिखता और कोई client उसे भेज नहीं सकता। जो values model को गढ़नी नहीं चाहिए - कीमतें, पहचान, अनुमतियाँ - उनकी जगह यहीं है।
* resolver के parameters उसी तरह resolve होते हैं: `Context`, कोई और `Resolve(...)`, या नाम से कोई tool argument। graph हर resolver को प्रति round ज़्यादा से ज़्यादा एक बार चलाता है, चाहे उसके कितने भी consumers हों; हर सवाल ठीक एक बार पूछा जाता है, और call के किसी सवाल के बाद फिर से शुरू होने पर कोई भी resolver दोबारा चल सकता है।
* खराब graphs registration के समय `InvalidSignature` के साथ fail होते हैं, call के बीच में नहीं।
* user से पूछने के लिए `Elicit(message, Model)` लौटाएँ, सिर्फ़ तब जब ज़रूरी हो। बिना wrap की annotations decline पर abort करती हैं; `ElicitationResult[T]` tool को branch करने देती है।
* client से LLM completion या roots की सूची माँगने के लिए `Sample(...)` या `ListRoots()` लौटाएँ; सादा result inject हो जाता है।
server startup पर एक बार जो state बनाता है, और handler उस तक कैसे पहुँचता है, वह **[Lifespan](lifespan.md)** page है।

View file

@ -0,0 +1,191 @@
---
translation:
sections: [335ca2a0b266f003, d1ad562d3fe87bc0, 0bb1396c86daeba4, d1cb1235bb9ee267, 833179c09d239c83, e5d6dec2d2e655e8]
tool: 1
---
# Elicitation {#elicitation}
जो tool अपना काम आधा कर चुका हो और उसके पास बस एक जवाब की कमी हो, उसका fail होना ज़रूरी नहीं।
**Elicitation** उसे पूछने देता है। tool call के बीच में user को एक सवाल मिलता है, और उसका जवाब उसी function call में वापस आ जाता है।
इसके दो mode हैं:
* **Form mode**: आपको एक value चाहिए (confirmation, तारीख, मात्रा)। आप fields बताते हैं, client form render करता है।
* **URL mode**: आपको user को कहीं और भेजना है (OAuth consent screen, payment page)। user वहाँ जो कुछ भी करता है, वह protocol से होकर नहीं गुज़रता।
और पूछने के दो तरीके हैं। जिसे पहले अपनाना चाहिए वह है **resolver**: आप सवाल को एक parameter पर टाँग देते हैं, और SDK पूछ लेता है - किसी भी connection पर, client चाहे किसी भी protocol पीढ़ी का हो। सीधा तरीका, `await ctx.elicit(...)`, *server* से *client* को जाने वाली request है, एक ऐसा channel जो सिर्फ़ legacy connection (spec version 2025-11-25 या उससे पहले) वाले client के लिए ही मौजूद होता है। दोनों इस page पर हैं; resolver से शुरू करें।
## resolver से पूछना {#ask-with-a-resolver}
जो सवाल पूरे tool को रोके रखता है - **पक्का? तीन मिलते-जुलते accounts में से कौन-सा?** - उसे tool body से निकालकर **resolver** में रखा जा सकता है, और framework उसे आपके लिए पूछ लेता है।
`Annotated[T, Resolve(fn)]` से annotate किया गया parameter tool body से पहले `fn` चलाकर भरा जाता है। जब resolver को value पहले से पता हो तो वह उसे सीधे लौटाता है, वरना `Elicit(...)` लौटाता है ताकि framework पूछ ले:
```python title="server.py" hl_lines="24-30 35-36"
--8<-- "docs_src/elicitation/tutorial004.py"
```
* `confirm_delete` tool के अपने `path` argument को नाम से पढ़ता है, folder की सूची बनाता है, और **सिर्फ़ तभी elicit करता है जब ज़रूरी हो** - खाली folder client तक एक भी round trip के बिना `Confirm(ok=True)` में resolve हो जाता है।
* `delete_folder` `ElicitationResult[Confirm]` annotate करता है, इसलिए framework पूरा नतीजा inject करता है और tool हर स्थिति को `match` करता है: accept-and-confirm, accept-but-keep (`ok=False`), decline, cancel।
* `confirm` parameter tool के input schema में कभी नहीं दिखता - client `path` देता है, resolver `confirm` देता है।
जब tool को branch करने की ज़रूरत न हो तो इसके बजाय unwrapped model (`Annotated[Confirm, Resolve(confirm_delete)]`) annotate करें: accept पर उसे model मिलता है और decline या cancel पर call एक error के साथ abort हो जाता है।
resolver **हर** connection पर काम करता है। legacy connection वाले client को SDK सवाल सीधे भेजता है; **2026-07-28** connection पर SDK call से सवाल **लौटाता** है, और client की अगली कोशिश जवाब साथ लाती है। आपके resolver को फ़र्क कभी पता नहीं चलता; नीचे जो होता है, वह **[Multi-round-trip requests](multi-round-trip.md)** है।
पूछना तो resolver के कामों में से सिर्फ़ एक है। सामान्य तंत्र - बिना पूछे compute होने वाली dependencies, dependencies की dependencies, model क्या दे सकता है और क्या नहीं - **[Dependencies](dependencies.md)** page पर है।
## tool के अंदर से पूछना {#ask-from-inside-the-tool}
tool अपनी body के बीच में रुककर भी पूछ सकता है।
!!! warning
`ctx.elicit()` और `ctx.elicit_url()` *server* से *client* को जाने वाली requests हैं - एक
ऐसा channel जो सिर्फ़ legacy connection (spec version **2025-11-25** या उससे पहले) वाले
client के लिए मौजूद होता है। **2026-07-28** connection पर server की ओर से शुरू की गई कोई
request नहीं होती, इसलिए ये calls fail हो जाते हैं। resolver दोनों पर काम करता है।
पूरी जानकारी **[Protocol versions](../protocol-versions.md)** में है।
`await ctx.elicit()` एक message और एक Pydantic model लेता है:
```python title="server.py" hl_lines="9-11 20-23 25"
--8<-- "docs_src/elicitation/tutorial001.py"
```
* **`Context`** parameter ही आपको `ctx.elicit` देता है; कोई भी tool इसे ले सकता है। उस object का अपना page है: **[Context](context.md)**।
* `AlternativeDate` उस जवाब का **schema** है जो आप चाहते हैं।
* tool `async def` है। होना ही चाहिए: यह बीच में रुककर किसी इंसान का इंतज़ार करता है।
* किसी भी दूसरी तारीख पर tool तुरंत लौट आता है। यह सिर्फ़ तभी पूछता है जब ज़रूरी हो।
* user जो तारीख accept करता है, वह `book_table` से ही होकर वापस जाती है। जवाब भी बाकी input की तरह input ही है: अगर विकल्प वाली तारीख भी पूरी तरह booked है तो उसके बारे में फिर से पूछा जाता है, आँख मूँदकर confirm नहीं किया जाता।
### client को क्या मिलता है {#what-the-client-receives}
client को आपका message मिलता है और उसके साथ model से generate किया गया एक JSON Schema:
```json
{
"properties": {
"accept_alternative": {
"description": "Try another date?",
"title": "Accept Alternative",
"type": "boolean"
},
"date": {
"default": "2025-12-26",
"description": "Alternative date (YYYY-MM-DD)",
"title": "Date",
"type": "string"
}
},
"required": ["accept_alternative"],
"title": "AlternativeDate",
"type": "object"
}
```
वही schema form है। `Field(description=...)` label है; default input को पहले से भर देता है और field को optional बना देता है। यह वही Pydantic-to-JSON-Schema तंत्र है जो **[Tools](../servers/tools.md)** tool के arguments के लिए बताता है।
!!! warning
elicitation schema tool के input schema जितना expressive नहीं होता। सिर्फ़ flat, primitive
fields: `str`, `int`, `float`, `bool`, या strings का `Literal` (यह `enum` बन जाता है)।
model के अंदर model रखें और `ctx.elicit` client को कुछ भी भेजे जाने से पहले ही raise कर देता है:
```text
TypeError: Elicitation schema field 'address' rendered as {'$ref': '#/$defs/Address'}, which is not a valid PrimitiveSchemaDefinition
```
आप किसी इंसान को काम के बीच में टोक रहे हैं। अगर जवाब में nesting चाहिए, तो उसे tool का
argument होना चाहिए था।
### तीन जवाब {#the-three-answers}
`result.action` बताता है कि user ने क्या किया, और संभावनाएँ ठीक तीन हैं:
* `"accept"`: user ने form submit किया। `result.data` एक `AlternativeDate` instance है, पहले से validated।
* `"decline"`: user ने मना कर दिया।
* `"cancel"`: user ने बिना कुछ चुने सवाल को हटा दिया।
`result.data` सिर्फ़ `"accept"` पर ही मौजूद होता है, इसीलिए उदाहरण पहले `result.action` जाँचता है। आपका type checker यह क्रम लागू करता है: `result.action == "accept"` के बाद `result.data` एक `AlternativeDate` है; उससे पहले `.data` है ही नहीं।
इनकार कोई error नहीं है। decline का क्या मतलब है, यह tool तय करता है (यहाँ, कोई booking नहीं) और model को सामान्य रूप से जवाब देता है।
!!! tip
जवाब आपके code तक पहुँचने से पहले आपके model के विरुद्ध validate होता है। जो client
`bool` के लिए `"maybe"` भेजता है, वह आपकी booking को खराब नहीं करता: call
schema-mismatch error के साथ fail हो जाता है, आपका `if` कभी नहीं चलता।
## user को URL पर भेजना {#send-the-user-to-a-url}
कुछ चीज़ें model या client से होकर कभी नहीं गुज़रनी चाहिए: credentials, card numbers, OAuth consent। इनके लिए आप data नहीं माँगते; आप user से कहीं जाने को कहते हैं:
```python title="server.py" hl_lines="10-14 23"
--8<-- "docs_src/elicitation/tutorial002.py"
```
* `ctx.elicit_url()` message, जाने के लिए **URL**, और आपकी चुनी हुई एक `elicitation_id` लेता है: कोई भी string जो आपके server के भीतर इस elicitation को पहचानती हो।
* result में एक action है और कुछ नहीं। `"accept"` का मतलब है user URL खोलने के लिए राज़ी हुआ, यह **नहीं** कि उसने दूसरी तरफ़ का काम पूरा कर लिया।
* payment out of band होता है, user के browser और आपके payment provider के बीच। MCP से होकर कोई content कभी वापस नहीं आता।
दूसरा tool देखें। जब आपके server को पता चलता है कि out-of-band flow पूरा हो गया (webhook, poll; यहाँ इसे दूसरे tool के रूप में दिखाया गया है), तो `ctx.session.send_elicit_complete(...)` उसी `elicitation_id` के साथ `notifications/elicitation/complete` भेजता है। इसी से client को पता चलता है कि वह *"waiting for payment..."* दिखाना बंद कर सकता है। इसके बिना client सिर्फ़ अंदाज़ा लगा सकता है।
## client की तरफ़ {#the-client-side}
servers पूछते हैं। clients `Client(...)` को एक **`elicitation_callback`** देकर जवाब देते हैं:
```python title="client.py" hl_lines="6-7 18"
--8<-- "docs_src/elicitation/tutorial003.py"
```
* एक ही callback दोनों modes संभालता है। `params` `ElicitRequestFormParams` और `ElicitRequestURLParams` का union है; `isinstance` ही branch है।
* URL के लिए, आप user को `params.url` दिखाते हैं और उसका चुना हुआ action लौटाते हैं। कभी कोई `content` नहीं।
* form के लिए, असली application `params.requested_schema` render करता है और user का input `content` के रूप में लौटाता है। यह वाला हमेशा एक तयशुदा जवाब के साथ हाँ कहता है, जो test में ठीक वैसा ही callback है जैसा आप चाहते हैं।
* callback देना ही **capability declaration** भी है: इसी से server को पता चलता है कि इस client से पूछा जा सकता है। client server के लिए और किन चीज़ों का जवाब दे सकता है, वह **[Client callbacks](../client/callbacks.md)** में है।
!!! info
elicitation *server* से *client* को जाने वाली request है, और ऐसी requests सिर्फ़
classic-handshake session पर ही होती हैं, इसीलिए यह client `mode="legacy"` देता है।
**2026-07-28** connection पर tool इसके बजाय call से सवाल **लौटाकर** पूछता है;
वह flow **[Multi-round-trip requests](multi-round-trip.md)** है।
### इसे आज़माएँ {#try-it}
`ctx.elicit` वाले form-mode `server.py` (`book_table` वाला) को Streamable HTTP पर शुरू करें (one-liner **[अपना server चलाना](../run/index.md)** में है), फिर client का `main()` चलाएँ और `book_table` से Christmas के दिन के लिए पूछें।
callback उसे भेजा गया सवाल print करता है:
```text
No tables for 2 on 2025-12-25. Would you like to try another date?
```
यह `{"accept_alternative": True, "date": "2025-12-27"}` से जवाब देता है, और tool, जो इस पूरे समय `await ctx.elicit(...)` के अंदर इंतज़ार कर रहा था, booking पूरी कर देता है:
```text
Booked a table for 2 on 2025-12-27.
```
अब URL-mode वाला `server.py` लगाएँ और उसी `main()` को `pay_deposit` की ओर कर दें: वही callback दूसरी branch लेता है, payment link print करता है, और tool *"Complete the payment in your browser."* के साथ लौटता है। एक round trip, call के बीच में, दोनों दिशाओं में।
!!! check
अब `Client` से `elicitation_callback=` हटाएँ और `book_table` को Christmas के दिन के लिए
फिर से call करें। पूरा call एक protocol error के साथ fail हो जाता है:
```text
Elicitation not supported
```
जिस client ने कोई callback register नहीं किया, उसने `elicitation` capability कभी declare ही
नहीं की, इसलिए पूछने के लिए कोई है ही नहीं। आपके tool को `"decline"` नहीं मिला; उसे exception
मिला। इसे ध्यान में रखकर design करें: हर elicitation के पास "अगर मैं पूछ न सकूँ तो?" का
एक समझदार जवाब होना चाहिए।
## सारांश {#recap}
* `Annotated[T, Resolve(fn)]` से annotate किया गया parameter resolver भरता है, जो पूछना ज़रूरी होने पर `Elicit(...)` लौटाता है। यह हर connection पर काम करता है।
* schema एक flat Pydantic model है: सिर्फ़ primitive fields, वापसी पर validate होते हैं।
* `result.action` `"accept"`, `"decline"` या `"cancel"` होता है; `result.data` सिर्फ़ accept पर मौजूद होता है।
* `await ctx.elicit(message, schema=Model)` tool body के अंदर से पूछता है, और `await ctx.elicit_url(message, url, elicitation_id)` उन सब चीज़ों के लिए है जो model से होकर नहीं गुज़रनी चाहिए (`ctx.session.send_elicit_complete(elicitation_id)` बताता है कि out-of-band हिस्सा पूरा हो गया)। दोनों server-to-client requests हैं: इन्हें legacy connection वाला client चाहिए।
* client एक `elicitation_callback` से जवाब देता है, params के type पर branch करके; उसे register करना ही capability declare करना है।
* 2026-07-28 connection पर server सवाल को push करने के बजाय लौटाता है; वही callback **[Multi-round-trip requests](multi-round-trip.md)** से भरता है।
उस return के नीचे जो कुछ भी है (retry loop, `requestState` की सुरक्षा, इसे खुद चलाना), वह **[Multi-round-trip requests](multi-round-trip.md)** है।

View file

@ -0,0 +1,24 @@
---
translation:
sections: [424930166c4bc6f3]
tool: 1
---
# आपके handler के अंदर {#inside-your-handler}
handler के arguments client से आते हैं। इसके **अलावा** वह जो कुछ पढ़ सकता है, और चलते समय जो कुछ कर सकता है, वह सब यहाँ है।
वह क्या पढ़ सकता है:
* **[Context](context.md)** वह एक अतिरिक्त parameter है जिसे कोई भी handler माँग सकता है: चल रही request, उसके headers, उसका session, और progress व change-notification के verbs।
* **[Dependencies](dependencies.md)** वे parameters हैं जिन्हें model कभी नहीं देखता; इन्हें `Resolve` के ज़रिए आपके अपने functions भरते हैं।
* **[Lifespan](lifespan.md)** उस state के बारे में है जिसे server startup पर एक बार बनाता है, और handler `Context` के ज़रिए उस तक कैसे पहुँचता है।
चलते समय वह क्या कर सकता है:
* **[Elicitation](elicitation.md)** से user से और input माँगना, और **[Multi-round-trip requests](multi-round-trip.md)**, 2026-07-28 का वह pattern जो इसे ले जाता है।
* **[Sampling और roots](sampling-and-roots.md)** से client से LLM completion या उसके workspace folders माँगना; ये deprecated हैं पर अब भी serve होते हैं।
* किसी धीमे काम पर **[Progress](progress.md)** बताना।
* **[Logging](logging.md)** से logs लिखना (standard error पर, server चलाने वाले के लिए)।
* **[Subscriptions](subscriptions.md)** से subscribe किए हुए clients को बताना कि कुछ बदला है।
अगर आपने अभी तक कोई handler register नहीं किया है, तो **[Tools](../servers/tools.md)** से शुरू करें। यहाँ का हर page मानकर चलता है कि आपके पास एक handler है।

View file

@ -0,0 +1,107 @@
---
translation:
sections: [f3ca8ac5f90f2dfa, 85a1ef3588ba0736, 563346d4d5804933, 9e3528340d0bab53]
tool: 1
---
# Lifespan {#lifespan}
ज़्यादातर असली servers पूरी ज़िंदगी भर कुछ न कुछ संभाले रखते हैं: database pool, HTTP client, load किया हुआ model।
इसे हर call पर दोबारा बनाना कोई नहीं चाहता, और इसे साफ़-सुथरे ढंग से बंद करना ज़रूर चाहिए। **lifespan** इसी के लिए है।
## Typed lifespan {#a-typed-lifespan}
lifespan एक `@asynccontextmanager` है जिसे server मिलता है और जो **एक object** `yield` करता है। आप जो भी yield करते हैं, वह server के चलते रहने तक हर handler को उपलब्ध रहता है।
```python title="server.py" hl_lines="25-31 34 38 40"
--8<-- "docs_src/lifespan/tutorial001.py"
```
इसे नीचे से ऊपर पढ़ें:
* `app_lifespan` `yield` से **पहले** `Database` को connect करता है और उसके **बाद**, `finally` में, disconnect करता है। यही startup और shutdown है।
* यह `AppContext` yield करता है, एक सादा dataclass जिसमें वे चीज़ें हैं जो आपने set up कीं। आज एक field, कल दस।
* `MCPServer("Bookshop", lifespan=app_lifespan)` ही पूरी wiring है।
* tool के अंदर, yield किया गया object `ctx.request_context.lifespan_context` है।
lifespan **एक बार** चलता है। server शुरू होने पर (पहली request से पहले) इसमें प्रवेश होता है और server रुकने पर इससे बाहर निकला जाता है। बीच की हर request वही `AppContext` साझा करती है।
!!! info
अगर आपने FastAPI का `lifespan` लिखा है, तो आप यह पहले से जानते हैं। वही decorator, वही `yield`, वही `finally`।
### model को क्या दिखता है {#what-the-model-sees}
कुछ नया नहीं। `ctx` एक **Context** parameter है, इसलिए SDK इसे inject करता है और यह input schema तक कभी नहीं पहुँचता:
```json
{
"type": "object",
"properties": {
"genre": {"title": "Genre", "type": "string"}
},
"required": ["genre"],
"title": "count_booksArguments"
}
```
`genre` ही एकमात्र argument है जो model दे सकता है। lifespan आपके server का अपना मामला है।
`@mcp.resource()` और `@mcp.prompt()` functions भी `ctx` parameter ले सकते हैं, जिसे सिर्फ़ `Context` लिखा जाता है; इसकी वजह अगला section बताता है। `ctx` में जो कुछ भी है, वह सब **[Context](context.md)** में है।
### यह सच में typed है {#it-really-is-typed}
annotation को फिर से देखें: `ctx: Context[AppContext]`।
इसी एक type parameter की वजह से आपके type checker के लिए `ctx.request_context.lifespan_context` एक `AppContext` **है**। `.db` autocomplete होता है; `.dbb` server चलाने से पहले ही error है।
इसकी जगह सिर्फ़ `Context` लिखें तो `lifespan_context` का type `dict[str, Any]` हो जाता है: type checker के पास यह जानने का कोई तरीका नहीं कि आपके lifespan ने क्या yield किया। runtime पर object फिर भी मौजूद रहता है; बस मदद चली जाती है।
!!! warning
`Context[AppContext]` **सिर्फ़ tools के लिए** लिखने का तरीका है। इसे किसी `@mcp.resource()` या
`@mcp.prompt()` function पर लगाएँ तो उस handler की हर call विफल हो जाती है। client को error वापस मिलता है,
और server log बताता है क्यों:
```text
Context is not available outside of a request
```
resources और prompts में सिर्फ़ `ctx: Context` लिखें। आपके lifespan ने जो object yield किया वह
runtime पर अब भी `ctx.request_context.lifespan_context` ही है; आप type parameter छोड़ते हैं,
object नहीं।
!!! tip
lifespan हमेशा होता है। अगर आप कोई pass नहीं करते, तो SDK का default एक खाली `dict` yield करता है,
इसलिए `ctx.request_context.lifespan_context` `{}` होता है, कभी `None` नहीं। इसी default की वजह से
सिर्फ़ `Context` लिखने पर इसका type `dict[str, Any]` होता है।
## इसे होते हुए देखें {#watch-it-happen}
"startup पहली request से पहले चलता है" ऐसा वाक्य है जिस पर आपको बिना देखे भरोसा नहीं करना पड़ना चाहिए।
server को सिर्फ़ lifecycle तक सीमित कर दें: `Database` को एक `connected` flag दें, `connect()` और `disconnect()` में उसे पलटें, और एक tool जोड़ें जो उसकी स्थिति बताए।
```python title="server.py" hl_lines="11 14 17 25 44"
--8<-- "docs_src/lifespan/tutorial002.py"
```
`database` module level पर एक ही वजह से है: ताकि आप इसे server के **बाहर** से देख सकें।
!!! check
तीन पल, तीन values:
* server शुरू होने से पहले, `database.connected` `False` है। module import करने से कुछ connect नहीं हुआ।
* जब यह चल रहा हो, `database_status` call करें और result `"connected"` मिलता है।
* server रोकें और `finally` block चलता है: `database.connected` फिर से `False` है।
काम ठीक वहीं हुआ जहाँ आपने उसे रखा: `yield` के आसपास, न import के समय और न हर request पर।
## सारांश {#recap}
* `lifespan=` एक `@asynccontextmanager` लेता है जिसे server मिलता है और जो एक object `yield` करता है।
* `yield` से पहले का code startup है। उसके बाद का `finally` shutdown है।
* यह एक बार चलता है, server की पूरी ज़िंदगी के इर्द-गिर्द, हर request पर नहीं।
* आप जो भी `yield` करते हैं, वह हर tool, resource और prompt में `ctx.request_context.lifespan_context` है।
* `ctx: Context[AppContext]` tools में इस access को पूरी तरह typed बना देता है। resources और prompts सिर्फ़ `Context` लेते हैं।
* `lifespan=` न हो तो खाली `dict` मिलता है, कभी `None` नहीं।
जो handler call के बीच रुककर user से वह पूछता है जो सिर्फ़ user ही जानता है, वह **[Elicitation](elicitation.md)** है।

View file

@ -0,0 +1,86 @@
---
translation:
sections: [c93a3e1aefd77955, 7851abd5ec54393b, f49d1ca2f330f9cd, c03764bd9dfeef7b, 4a0391691a674ae4, 2df5cd279eabf9f5]
tool: 1
---
# Logging {#logging}
किसी tool से log वैसे ही करें जैसे किसी भी दूसरे Python function से करते हैं: standard library के साथ।
MCP में protocol स्तर की **logging capability** है: server अपने log messages को `Context` object के methods के ज़रिए notifications के रूप में client तक भेज सकता था। spec का 2026-07-28 revision **उस capability को deprecate करता है और उसकी जगह कुछ नहीं लाता**, इसलिए ये docs उसे नहीं सिखाते। क्या-क्या deprecated है और उसके बदले क्या करना है, इसकी पूरी सूची **[Deprecated features](../deprecated.md)** में है।
उसके बदले आप वही करते हैं जो हर दूसरे Python program में करते हैं: standard library।
## log करने वाला tool {#a-tool-that-logs}
```python title="server.py" hl_lines="1 5 13"
--8<-- "docs_src/logging/tutorial001.py"
```
* `logging.getLogger(__name__)` आपको आपके module के नाम वाला logger देता है। इसे एक बार बनाएँ, सबसे ऊपर।
* tool के अंदर आप `logger.info(...)` को किसी भी दूसरे function की तरह call करते हैं। न कुछ inject करना है, न कुछ `await` करना है, न कुछ MCP-specific है।
!!! check
tool को call करें और पूरा result देखें:
```python
result.content # [TextContent(text="Found 3 books matching 'dune'.")]
result.structured_content # {'result': "Found 3 books matching 'dune'."}
```
log line इसमें कहीं नहीं है। logging **आपके** लिए है, उस व्यक्ति के लिए जो server चला रहा है। model
इसे कभी नहीं देखता। अगर model को कुछ पढ़ना चाहिए, तो उसे `return` करें।
## यह कहाँ जाता है {#where-it-goes}
**stdio** server के लिए यह सवाल आम से ज़्यादा मायने रखता है। host ने आपके server को subprocess के रूप में शुरू किया है और उसके **stdout** से MCP messages पढ़ रहा है। standard error आपका है।
standard library पहले से सही काम करती है: log output default रूप से `sys.stderr` पर जाता है। आपकी `logger.info(...)` lines terminal में पहुँचती हैं (या जहाँ भी host subprocess का stderr इकट्ठा करता है), और protocol stream साफ़ रहता है।
!!! tip
stdio server में `print()` न करें। `print` **stdout** पर लिखता है, और stdout protocol का है।
serve करते समय SDK उस stdout को stderr की ओर मोड़ देता है जो सच में **flush** हुआ हो, ताकि वह
wire को खराब न कर सके, लेकिन block-buffered process में `print()` आमतौर पर `sys.stdout` के buffer में
बिना flush हुए पड़ा रहता है, जब तक interpreter exit पर उसे खाली नहीं करता, सीधे protocol stream पर। जब उसे
मोड़ा भी जाता है, तब भी वह line log output के बीच कच्ची ही पहुँचती है, बिना level के, बिना logger नाम के, और बिना उसे filter करने के किसी तरीके के।
`logger.debug("got here")` उतनी ही एक line की मेहनत है और सही जगह जाता है।
## Level {#the-level}
आपको `logging.basicConfig()` खुद call करने की ज़रूरत नहीं है। `MCPServer` बनाते ही यह पहले से हो चुका है, standard error की ओर इशारा करते handler के साथ, उस level पर जो आप `log_level=` में देते हैं, इसलिए अपनी `logger.debug(...)` lines देखने के लिए `MCPServer("Bookshop", log_level="DEBUG")` ही काफ़ी है।
default `"INFO"` है।
`logging.basicConfig()` पहले से मौजूद handlers को कभी नहीं बदलता। अगर आप server बनाने से पहले खुद logging configure करते हैं, तो आपका configuration ही चलता है।
## इसे आज़माएँ {#try-it}
server को MCP Inspector के साथ चलाएँ:
```console
uv run mcp dev server.py
```
**Tools** tab से `search_books` को call करें। Inspector आपको result दिखाता है: सिर्फ़ return value। यह line
```text
Searching for 'dune'
```
standard error पर गई: terminal पर, wire पर नहीं।
!!! info
अगर आपको असल में **tracing** चाहिए (हर request, उसमें कितना समय लगा, वह fail हुई या नहीं), तो आपको
log lines नहीं, spans चाहिए। आपका server उन्हें पहले से भेजता है: SDK बिना कुछ configure किए हर
message को OpenTelemetry से trace करता है। **[OpenTelemetry](../run/opentelemetry.md)** देखें।
## सारांश {#recap}
* MCP protocol की logging capability को 2026-07-28 spec deprecate करता है और उसकी जगह कुछ नहीं लाता। उस पर कुछ न बनाएँ।
* module स्तर पर `logger = logging.getLogger(__name__)`, tool में `logger.info(...)`। पूरा pattern बस इतना ही है।
* log output कभी model तक नहीं पहुँचता। सिर्फ़ वही value पहुँचती है जो आप `return` करते हैं।
* standard error आपका है; stdout protocol का है। serve करते समय SDK flush हुए भटके stdout को stderr की ओर मोड़ देता है, लेकिन बिना flush हुआ `print()` फिर भी exit पर wire पर खाली हो सकता है, और मोड़ी गई lines बिना label के पहुँचती हैं; `logging` इस्तेमाल करें, जिसका handler हर record को flush करता है।
* `MCPServer(..., log_level="DEBUG")` level तय करता है, और जो logging configuration आपने पहले बनाया हो उसे छेड़ा नहीं जाता।
जुड़े हुए clients को यह बताना कि आपके server पर कुछ बदला है (tool list, कोई resource), **[Subscriptions](subscriptions.md)** का विषय है।

View file

@ -0,0 +1,191 @@
---
translation:
sections: [74011e683045eea9, 9b64cc175c18b6a9, 4b41be4824030397, e3b1502da786ec33, 71e41161f143c6a9, 9ec2c1eeb8c36378, 8dd027377d46448b, f81491125dcbfe8b]
tool: 1
---
# Multi-round-trip requests {#multi-round-trip-requests}
कभी-कभी कोई tool एक round trip में पूरा नहीं हो पाता। उसे कुछ ऐसा चाहिए जो सिर्फ़ user के पास है: कोई चुनाव, कोई पुष्टि, कोई credential।
2026-07-28 से पहले server यह चीज़ **वापस call करके** लेता था: मूल request को संभालने के बीच में ही client की तरफ़ अपनी request खोलकर (कोई elicitation, कोई sampling call)। 2026-07-28 spec उस back-channel को बंद कर देता है।
इसके बजाय, server **लौटाता** है।
## लौटाएँ, वापस call न करें {#return-dont-call-back}
server `tools/call` का जवाब `CallToolResult` की जगह **`InputRequiredResult`** से देता है। इसके दो fields सारा काम करते हैं:
* **`input_requests`**: server को अभी और क्या चाहिए, एक dict के रूप में जिसकी keys server ने खुद चुनी हैं। हर value एक `ElicitRequest`, `CreateMessageRequest`, या `ListRootsRequest` है।
* **`request_state`**: एक opaque token। client retry पर इसे ज्यों का त्यों वापस भेजता है। इसे पढ़ने वाला सिर्फ़ server है।
client हर request पूरी करता है, फिर **उसी tool को दोबारा** call करता है, अपने जवाब `input_responses` में और token `request_state` में लेकर। अब server के पास वह है जो पहले नहीं था, और वह सामान्य `CallToolResult` लौटाता है।
पूरा protocol बस इतना ही है। हर चरण client से server की ओर जाने वाली साधारण request है। उल्टी दिशा में कभी कुछ नहीं बहता।
## server की तरफ़ {#the-server-side}
`@mcp.tool()` पर आप इसे शायद ही कभी हाथ से बनाते हैं: ऐसी dependency घोषित करें जो user से पूछती है (`Elicit`), client के LLM से sample लेती है (`Sample`), या उसके roots की सूची लेती है (`ListRoots`), और SDK आपके लिए `InputRequiredResult` लौटा देता है; वह रूप **[Dependencies](dependencies.md)** page पर है। दोनों रूप आपस में नहीं मिलते: एक call के पास `input_responses`/`request_state` का एक ही channel होता है, इसलिए `Resolve(...)` parameters इस्तेमाल करने वाला tool अपनी body से `InputRequiredResult` भी नहीं लौटा सकता। घोषित `InputRequiredResult` return registration के समय ही अस्वीकार हो जाता है (`InvalidSignature`), और बिना घोषित वाला runtime पर call को fail कर देता है। हाथ से बनाने वाला रूप **low-level** `Server` है, जिसके `on_call_tool` handler को दोनों में से कोई भी result type लौटाने की अनुमति है:
```python title="server.py" hl_lines="43-46"
--8<-- "docs_src/mrtr/tutorial001.py"
```
* `on_call_tool` का type `-> CallToolResult | InputRequiredResult` है। दूसरा वाला लौटाना ही server की तरफ़ का पूरा API है।
* पहली call पर `params.input_responses` `None` है, इसलिए guard चलता है और handler जवाब देने के बजाय पूछता है।
* retry पर, client का भेजा `ElicitResult` **उसी key** (`"region"`) के नीचे रखा मिलता है जो server ने `input_requests` में इस्तेमाल की थी।
उस file का बाकी सब कुछ (स्पष्ट `input_schema`, हाथ से बना `CallToolResult`) साधारण low-level `Server` है, जो **[Low-level Server](../advanced/low-level-server.md)** में बताया गया है। यह page सिर्फ़ दूसरा return type जोड़ता है।
## tools से आगे {#beyond-tools}
`tools/call` में कुछ खास नहीं है: 2026-07-28 पर server `prompts/get` और `resources/read` का जवाब भी इसी तरह दे सकता है। `MCPServer` पर, `@mcp.prompt()` function — या `@mcp.resource()` **template** function — खुद `InputRequiredResult` लौटाता है और retry के जवाब context से पढ़ता है:
```python title="server.py" hl_lines="20 22 24"
--8<-- "docs_src/mrtr/tutorial004.py"
```
* पहला round `InputRequiredResult` लौटाता है। retry पर, `ctx.input_responses` में वही keys के नीचे जवाब होते हैं और function अपना साधारण result लौटाता है — यहाँ prompt messages, template resource के लिए resource content।
* आपका set किया `request_state` wire पार करने से पहले seal होता है और echo पर verify होता है, server पर बाकी सब की तरह; नीचे **[`requestState` की सुरक्षा](#protecting-requeststate)** बताता है कि seal आपको क्या देता है और keys कब configure करनी होती हैं।
* जब dependency वाला रूप फिट न बैठे, तो `@mcp.tool()` function भी इसी तरह सीधे result लौटा सकता है।
* static `@mcp.resource()` functions इसमें हिस्सा नहीं लेते: वे `Context` नहीं लेते, इसलिए retry कभी पढ़ ही नहीं सकते। सिर्फ़ template resources पूछ सकते हैं।
* नीचे दिए पीढ़ी के नियम बिना बदलाव लागू होते हैं: pre-2026 session पर `InputRequiredResult` लौटाना वही `-32603` है जिसका ज़िक्र warning में है।
## client की तरफ़ {#the-client-side}
`Client` आपके लिए loop चलाता है।
वे callbacks register करें जो server माँग सकता है (`elicitation_callback`, `sampling_callback`, `list_roots_callback`) और tool call करें। जब `InputRequiredResult` आता है, `Client` `input_requests` की हर entry को मेल खाते callback के पास भेजता है, जवाबों और echo किए `request_state` के साथ retry करता है, और तब तक चलता रहता है जब तक `CallToolResult` वापस न आ जाए:
```python title="client.py" hl_lines="11 12"
--8<-- "docs_src/mrtr/tutorial003.py"
```
* वह `elicitation_callback` वही है जिस पर pre-2026 server का back-channel `elicitation/create` पहुँचता। `sampling/createMessage` के लिए `sampling_callback` और `roots/list` के लिए `list_roots_callback` पर भी यही बात लागू है: 2026-07-28 पर अलग से चलने वाले server->client RPC चले गए हैं, लेकिन हूबहू वही `ElicitRequest` / `CreateMessageRequest` / `ListRootsRequest` payloads `input_requests` के अंदर आते हैं और उन्हीं तीन callbacks तक पहुँचते हैं। callbacks का एक ही set दोनों पीढ़ियों को serve करता है।
* `call_tool` सादा `CallToolResult` लौटाता है। बीच के rounds caller को नहीं दिखते।
* `get_prompt` और `read_resource` भी यही loop चलाते हैं।
!!! check
callback न लगाएँ तो loop पहले ही round में fail हो जाता है: SDK का stand-in callback
हर elicitation का जवाब error से देता है, और `call_tool` *"Elicitation not supported"*
message के साथ `MCPError` raise करता है।
loop की सीमा है। `Client(..., input_required_max_rounds=10)` default cap है; जो server उससे आगे भी `InputRequiredResult` लौटाता रहे, वह `call_tool` से raise करवा देता है। अगर किसी round में सिर्फ़ `request_state` हो और कोई `input_requests` न हो, तो `Client` retry करने से पहले थोड़ी देर sleep करता है (50ms से दोगुना होते हुए 250ms की सीमा तक), ताकि जो server बस *"अभी पूरा नहीं हुआ"* कह रहा है उसे लगातार poll न किया जाए।
### loop खुद चलाना {#driving-the-loop-yourself}
एक ही process वाले client के लिए auto-loop काफ़ी है। loop खुद तब संभालें जब:
* आपका client **distributed** है: जो process user को सवाल दिखाता है, वह वही process नहीं है जिसने `call_tool` call किया था, इसलिए retry कोई दूसरा worker भेजता है। `request_state` वह सहेजा जा सकने वाला token है जिसे आप अपने storage के ज़रिए उस सीमा के पार ले जाते हैं, और `input_responses` वह है जो दूसरी तरफ़ से उसके साथ वापस आता है।
* आप हर round को **जाँचना** चाहते हैं: `input_requests` की हर entry को log या audit करना, कुछ तरह की requests को मना करना, या चरणों के बीच अपना backoff लगाना।
* आपको round की गिनती के बजाय **घड़ी के समय** की सीमा चाहिए: `input_required_max_rounds` पर निर्भर रहने के बजाय अपने loop को `anyio.fail_after(...)` में लपेटें।
नीचे के session पर उतरें, जहाँ `allow_input_required=True` आपको सीधे union देता है:
```python title="client.py" hl_lines="12 13 19"
--8<-- "docs_src/mrtr/tutorial002.py"
```
* `client.session.call_tool(..., allow_input_required=True)` return type को `CallToolResult | InputRequiredResult` तक चौड़ा कर देता है। `isinstance` ही उसे वापस संकरा करता है।
* `request_state` अब आपके हाथ में है। चरणों के बीच इसे लिखकर रख लें तो बातचीत किसी नए process से फिर शुरू हो सकती है।
* `input_requests` की हर entry के लिए आप `input_responses` में **उसी key** के नीचे एक `InputResponse` रखते हैं। `fulfil` वह जगह है जहाँ आपका UI आता है; यह वाला जवाब hard-code करता है।
* हर चरण में वही tool name, वही `arguments`। retry मूल call को दोबारा पूरा करना है, कोई नया method नहीं।
## `requestState` की सुरक्षा {#protecting-requeststate}
ऊपर सब कुछ `request_state` को echo मानता है, और wire पर वह बस इतना ही है। लेकिन client इसे चरणों के बीच अपने पास रखता है (processes के पार इसे लिखकर रखना ही वह चीज़ है जिसकी पिछले section ने अनुमति दी), इसलिए जो वापस आता है वह **client का दिया input** है: उसमें बदलाव हो सकता है, वह expire हो सकता है, या किसी बिल्कुल अलग call से उठाया गया हो सकता है। spec की माँग है कि जब भी यह state authorization, resource access, या business logic पर असर डाल सकता हो, servers इस state की integrity सुरक्षित रखें और verification fail होने पर round को अस्वीकार करें।
`MCPServer` default रूप से इसकी सुरक्षा करता है। हर server बाहर जाने वाले `requestState` को seal करता है और हर echo को verify करता है — resolver state और हाथ से बना state, दोनों — process शुरू होने पर बनी key के तहत। आपको कुछ configure नहीं करना, plaintext लिखना है और plaintext पढ़ना है; wire पर सिर्फ़ एक opaque encrypted token जाता है।
default key process के साथ ही जीती-मरती है, और एक process से आगे deploy करने से पहले यही एक बात आपको पता होनी चाहिए:
```python
from mcp.server.mcpserver import MCPServer, RequestStateSecurity
# Multi-instance or restart-surviving: one or more shared secret keys (>= 32 bytes each).
mcp = MCPServer("fleet", request_state_security=RequestStateSecurity(keys=[key]))
```
* **default (बिना configuration)** एक process के लिए ठीक है: stdio, या ठीक एक HTTP worker। जो retry किसी दूसरे worker पर, load balancer के पीछे किसी दूसरे instance पर, या restart के बाद उसी server पर पहुँचती है, वह ऐसी key के तहत seal हुई होती है जो उस process के पास नहीं है — client को नीचे वाला तय rejection मिलता है और उसे flow फिर से शुरू करना पड़ता है।
* **`keys=[...]`** तब ज़रूरी है जब भी retry किसी **दूसरे instance** तक पहुँच सकती हो (multi-worker `uvicorn`, load-balanced HTTP) या restarts के पार बचनी हो: हर instance वह verify करता है जो किसी भी sibling ने mint किया। वही मशीनरी, बनाई गई key की जगह आपका secret।
* अपनी crypto के लिए, जैसे कोई KMS या मौजूदा token service, `keys` की जगह `RequestStateSecurity(codec=...)` दें; नीचे **[अपनी crypto लाएँ](#bring-your-own-crypto)** contract बताता है।
### seal में क्या होता है {#what-the-seal-carries}
default हो या configured, wire पर `requestState` एक encrypted, authenticated token है। आपका code इसे कभी नहीं देखता: handlers और resolvers plaintext लिखते हैं और plaintext पढ़ते हैं (`ctx.request_state`); SDK बाहर जाते समय seal करता है और अंदर आते समय verify करता है। integrity के अलावा, हर token इनसे बँधा होता है:
* **एक समय सीमा।** हर round नई expiry के साथ दोबारा seal करता है, इसलिए `RequestStateSecurity(ttl=...)` (default 600 seconds) हर round के सोचने के समय को बाँधता है, पूरे flow को नहीं।
* **authenticated principal।** जब request में ऐसा OAuth access token हो जिसे SDK ने validate किया, तो state उस token के client, issuer, और subject से बँध जाता है: एक user के लिए mint हुआ state दूसरे user के तहत fail होता है, भले ही दोनों users एक ही OAuth client साझा करते हों। जो verifier कोई subject नहीं देता, उसके साथ binding घटकर सिर्फ़ client identity तक रह जाती है, जो URL-आधारित client IDs में उस client software के हर user के बीच साझा होती है। जब auth SDK के बाहर खत्म होता है (आगे लगा proxy), या transport unauthenticated है, तो बाँधने के लिए कोई principal नहीं होता और यह जाँच निष्क्रिय रहती है, जब तक `RequestStateSecurity(bind_principal=...)` आपके अपने identity signal से कोई principal न दे। आपका token verifier जो भी components देता है, उन्हें लगातार एक जैसे देना चाहिए: जो verifier कुछ requests पर subject शामिल करे और दूसरों पर छोड़ दे, वह flow के बीच में principal बदल देता है, और चल रहे rounds अस्वीकार हो जाते हैं।
* **मूल request।** method, tool या prompt का नाम (या resource URI), और arguments का digest। किसी दूसरे tool, दूसरे arguments, या दूसरे method के विरुद्ध replay किया token fail होता है।
* **पूछा गया ठीक वही सवाल।** हर resolver जवाब उस rendered सवाल से जुड़ा होता है जो client को दिखाया गया था, उस round पर भी जब वह पहली बार आता है और तब भी जब दर्ज किया जवाब बाद में दोबारा इस्तेमाल होता है। बदले हुए शब्दों वाले message या बदले schema के साथ redeploy करें तो server बासी जवाब खाने के बजाय दोबारा पूछता है। यही जुड़ाव दूसरी दिशा में भी असर करता है: messages tool के arguments से बनाएँ, हर call के data से नहीं। timestamp या live rate से बना message हर round में अलग render होता है, इसलिए हर दर्ज जवाब बासी दिखता है और server तब तक दोबारा पूछता रहता है जब तक client की round सीमा call को खत्म न कर दे।
यह सब SDK का काम है, आपका नहीं, और अगर आप अपना codec लाते हैं तो codec का भी नहीं।
### keys बदलना (rotation) {#rotating-keys}
`keys[0]` नया state seal करती है; सूची की हर key verify करती है। zero-downtime rotation तीन चरणों में होता है, हर चरण अगले से पहले पूरी तरह roll out:
```python
RequestStateSecurity(keys=[OLD, NEW]) # 1: every instance learns to verify NEW; OLD still mints
RequestStateSecurity(keys=[NEW, OLD]) # 2: NEW mints; in-flight OLD state keeps verifying
RequestStateSecurity(keys=[NEW]) # 3: one ttl after phase 2 is fully out, retire OLD
```
minter को कभी पहले promote न करें: ऐसी key के तहत mint करना जिसे कोई instance अभी verify नहीं कर सकता, rollout के बीच में चल रहे rounds गिरा देता है।
keys एक service तक सीमित हैं। sealed envelope में server का नाम audience claim के रूप में भी होता है, इसलिए किसी दूसरी service का mint किया token, जो संयोग से वही secret साझा करती हो, वैसे भी अस्वीकार हो जाता है। claim उतना ही विशिष्ट है जितना नाम, इसलिए जिस server को स्पष्ट policy दी गई हो उसका असली नाम होना चाहिए या उसे `RequestStateSecurity(audience=...)` set करना चाहिए — बिना नाम वाला construction पर ही raise करता है। `audience=` जान-बूझकर बनाई multi-service topologies के भी काम आता है जहाँ एक service को दूसरी का mint किया state स्वीकार करना हो। (बिना configuration वाला default इससे मुक्त है: उसकी key कभी process से बाहर नहीं जाती, इसलिए audience claim के पास जोड़ने को कुछ नहीं है।)
### अपनी crypto लाएँ {#bring-your-own-crypto}
`RequestStateSecurity(codec=...)` ऐसी कोई भी चीज़ लेता है जिसमें `seal(bytes) -> str` और `unseal(str) -> bytes` हों और जो हर उस token के लिए `InvalidRequestState` raise करे जो उसने mint नहीं किया। इसका classic रूप KMS के विरुद्ध envelope encryption है, जहाँ आप startup पर एक बार data key unwrap करते हैं और हर token की crypto local रखते हैं:
```python title="server.py" hl_lines="12 26-27 34-35 38"
--8<-- "docs_src/mrtr/tutorial005.py"
```
TTL, principal binding, और request binding codec का काम **नहीं** हैं: SDK हर codec के लिए इन्हें `seal` से पहले payload में डालता है और `unseal` के बाद दोबारा verify करता है। codec की ज़िम्मेदारियाँ सिर्फ़ integrity (छेड़छाड़ का मतलब raise) और, आदर्श रूप से, confidentiality हैं।
### जब verification fail हो {#when-verification-fails}
हर inbound failure, चाहे छेड़छाड़ हुई हो, expire हुआ हो, किसी दूसरी request या principal के विरुद्ध replay हुआ हो, या ऐसी key के तहत seal हुआ हो जिसे यह server नहीं जानता, एक ही जवाब पाता है:
```json
{"code": -32602, "message": "Invalid or expired requestState"}
```
हर कारण के लिए एक ही तय message, ताकि wire कभी न बताए कि कौन सी जाँच fail हुई; असली कारण server log में जाता है। `tools/call`, `prompts/get`, और `resources/read` पर हर inbound `requestState` जाँचा जाता है, वह भी जो ऐसे handler के लिए आए जो कभी state mint नहीं करता। व्यवहार में सबसे आम rejection कोई हमलावर नहीं है — यह default process-local key का restart से पहले वाली या किसी दूसरे instance की retry से टकराना है; client flow फिर शुरू करता है, और जब यह मायने रखता हो तो `keys=[...]` ही उपाय है।
### हाथ से बना state {#hand-built-state}
जो `request_state` आप खुद set करते हैं (tool, prompt, या resource-template function से `InputRequiredResult` लौटाकर), वह उसी मशीनरी से seal और verify होता है जिससे resolver state, code में एक भी बदलाव के बिना: plaintext लिखें, plaintext पढ़ें, और ऊपर की हर binding लागू होती है।
एक चीज़ जो SDK आपके लिए तय नहीं कर सकता, configured होने पर भी, वह है सवाल की पहचान: उसे नहीं पता कि आपके state में कोई जवाब **आपके** किस सवाल का है। अगर आप जवाब सवाल की key से store करते हैं, तो state में अपना सवाल-identifier शामिल करें और retry पर उसे जाँचें।
low-level `Server` बिना-batteries वाला स्तर है: `MCPServer` के विपरीत, जब तक आप boundary खुद न जोड़ें तब तक कुछ seal नहीं होता, और ऐसा करने तक आपका `request_state` ठीक वैसे ही wire पार करता है जैसा लिखा गया। एक line वाला opt-in **[Low-level Server](../advanced/low-level-server.md#the-other-handlers)** में दिखाया गया है।
## एक 2026-07-28 result {#a-2026-07-28-result}
`InputRequiredResult` सिर्फ़ protocol version **2026-07-28** पर मौजूद है। in-memory `Client(server)` इसे आपके लिए negotiate करता है; wire पर, `mode="auto"` इसे खोज लेता है। connect करने के बाद `client.protocol_version` बताता है कि आपको क्या मिला।
!!! warning
pre-2026 session के पास `InputRequiredResult` रखने की कोई जगह नहीं है। `mode="legacy"` connection पर
अपने handler से इसे लौटाएँ तो runner इसे negotiate हुए version में serialize नहीं कर पाता; client
को `-32603` *"Handler returned an invalid result"* error वापस मिलता है। जो server दोनों पीढ़ियों को
serve करता है, उसे इसका सहारा लेने से पहले `ctx.protocol_version` जाँचना होगा।
!!! info
**URL-mode elicitation** 2026 connection पर ठीक इसी mechanism पर चलता है। `input_requests`
की entry ऐसी `ElicitRequest` है जिसके params `ElicitRequestURLParams` हैं; user out-of-band
flow पूरा करता है और आपका client call retry करता है। वही loop, कोई नया API नहीं। high-level
server वाला हिस्सा **[Elicitation](elicitation.md)** में है।
## सारांश {#recap}
* 2026-07-28 पर जिस server को call के बीच input चाहिए, वह `InputRequiredResult` **लौटाता** है। वह client की तरफ़ कभी request नहीं खोलता।
* `input_requests` वह है जो उसे चाहिए। `request_state` एक opaque resume token है जिसे सिर्फ़ server पढ़ता है।
* `Client` आपके लिए retry loop चलाता है: `elicitation_callback` / `sampling_callback` / `list_roots_callback` register करें और `call_tool` सादा `CallToolResult` लौटाता है। `input_required_max_rounds` (default 10) इसकी सीमा है।
* rounds जाँचने या सहेजने के लिए `client.session.call_tool(..., allow_input_required=True)` इस्तेमाल करें और `while isinstance(result, InputRequiredResult)` loop खुद संभालें।
* `@mcp.tool()` पर, user से पूछने वाली dependency यह result आपके लिए बनाती है (**[Dependencies](dependencies.md)**); **low-level** `Server` हाथ से बनाने वाला रूप है।
* prompts और resources भी हिस्सा लेते हैं: `@mcp.prompt()` या template `@mcp.resource()` function खुद `InputRequiredResult` लौटाता है और retry पर `ctx.input_responses` पढ़ता है।
* `requestState` client के दिए input के रूप में वापस आता है, इसलिए `MCPServer` इसे default रूप से seal करता है — resolver state और हाथ से बना state, दोनों — process-local key के तहत; multi-instance deployments `RequestStateSecurity(keys=[...])` (या custom codec) देते हैं ताकि हर instance वह verify कर सके जो किसी sibling ने mint किया। seal हर token को एक समय सीमा, मूल request, और authenticated principal से बाँधता है, जब request में SDK का validate किया auth हो या `bind_principal=` आपका अपना identity signal दे (**[`requestState` की सुरक्षा](#protecting-requeststate)**)।
यही वह mechanism है जो server-initiated sampling और push-शैली के बाकी back-channel की जगह लेता है; **[Deprecated features](../deprecated.md)** देखें।

View file

@ -0,0 +1,121 @@
---
translation:
sections: [5315262fe26b33e1, 9d8e98840f1b78f0, 0284b215e85366c4, 8534d8dbb4053a70, 2966fac6fe697007]
tool: 1
---
# Progress {#progress}
जो tool तीस सेकंड लेता है और तीस सेकंड तक कुछ नहीं बोलता, वह टूटा हुआ लगता है।
**Progress notifications** इसे ठीक करते हैं। Tool बताता है कि काम कितना हो चुका है; client तय करता है कि उससे क्या दिखाए: bar, spinner, या log line।
## Tool से report करें {#report-it-from-the-tool}
एक **`Context`** parameter लें और `report_progress` call करें:
```python title="server.py" hl_lines="8 11"
--8<-- "docs_src/progress/tutorial001.py"
```
तीन arguments, और उनका मतलब आप तय करते हैं:
* `progress`: आप कहाँ तक पहुँचे हैं। Spec की माँग है कि यह हर report के साथ **बढ़े**; कोई value न दोहराएँ, न पीछे जाएँ।
* `total`: कुल कितना है, अगर आपको पता हो। Optional।
* `message`: **इसी** चरण के बारे में एक human-readable line। Optional।
`ctx` अपने type hint की वजह से inject होता है और model इसे कभी नहीं देखता: `import_catalog` के input schema में सिर्फ़ एक property है, `urls`। **[Context](context.md)** page पूरी तरह उसी object के बारे में है; progress उन चीज़ों में से एक है जो वह आपको देता है।
## Client से सुनें {#listen-for-it-from-the-client}
Client **हर call पर** अलग से opt in करता है, `call_tool` को `progress_callback=` देकर:
```python title="client.py" hl_lines="7 16"
import anyio
from mcp import Client
from server import mcp
async def show(progress: float, total: float | None, message: str | None) -> None:
print(f"{message} ({progress}/{total})")
async def main() -> None:
async with Client(mcp) as client:
result = await client.call_tool(
"import_catalog",
{"urls": ["https://example.com/a.json", "https://example.com/b.json"]},
progress_callback=show,
)
print(result.structured_content)
anyio.run(main)
```
Callback एक `async` function है जो ठीक वही लेता है जो server ने report किया: `progress`, `total`, `message`।
!!! info
`Client(mcp)` सीधे server object से जुड़ता है, memory में, वही client जिस पर **[Testing](../get-started/testing.md)**
page बना है। `Client` चाहे कोई भी transport इस्तेमाल करे, `progress_callback` parameter वही रहता है;
जो **timing** आप अभी देखने वाले हैं वह in-memory connection की है। वह आपका callback inline चलाता है,
इसलिए हर report `call_tool` के लौटने से पहले पहुँच जाती है। असली transport पर notifications और result
में होड़ लगती है, और एक धीमा callback `call_tool` के लौटने के बाद भी चल रहा हो सकता है।
### इसे आज़माएँ {#try-it}
`client.py` को `server.py` के बगल में रखें और चलाएँ:
```console
python client.py
```
```text
Imported https://example.com/a.json (1/2)
Imported https://example.com/b.json (2/2)
{'result': 'Imported 2 records.'}
```
Server पर हर `await ctx.report_progress(...)` client पर `show` का एक call बना, उसी क्रम में, और दोनों lines `call_tool` के लौटने से **पहले** print हुईं। Progress result में बंडल होकर नहीं आता; tool के काम करते रहने के दौरान ही stream होता है।
!!! warning
`progress_callback` **call** का है, `Client` का नहीं। इसके लिए कोई constructor argument नहीं है,
क्योंकि अलग-अलग calls को अलग-अलग callbacks चाहिए: एक download bar चलाता है, अगला
एक log line।
!!! check
अब `progress_callback=show` हटा दें और फिर से चलाएँ:
```text
{'result': 'Imported 2 records.'}
```
कोई error नहीं, कोई warning नहीं, वही result। जब caller ने progress नहीं माँगा हो तब
`report_progress` **no-op** है, इसलिए आप बिना शर्त report करें और कभी यह सोचने की ज़रूरत नहीं
कि कोई सुन भी रहा है या नहीं।
## जब total पता न हो {#when-you-dont-know-the-total}
`total` तब के लिए है जब आपको denominator पता हो। अक्सर नहीं होता: आप कोई feed खाली कर रहे हैं, cursor पर चल रहे हैं, बिना length header वाली कोई चीज़ download कर रहे हैं।
इसे छोड़ दें:
```python title="server.py" hl_lines="20"
--8<-- "docs_src/progress/tutorial002.py"
```
Callback को `total=None` मिलता है। Client अब भी **activity** दिखा सकता है ("3 imported so far..."), लेकिन percentage नहीं दिखा सकता। ज़्यादा सुंदर bar पाने के लिए कोई total न गढ़ें।
!!! tip
ज़रूरी नहीं कि `progress` किसी ख़ास चीज़ को गिने। Bytes, rows, pages: वह unit चुनें जिसे
user पहचाने, और सिर्फ़ वही `total` वादा करें जिसे आप निभा सकें।
## सारांश {#recap}
* `Context` लेने वाले किसी भी tool से `await ctx.report_progress(progress, total=None, message=None)`।
* Client `call_tool` को `progress_callback=` देता है: हर call पर, कभी `Client` पर नहीं।
* Callback `async (progress, total, message) -> None` है और tool के चलते रहने के दौरान ही fire होता है।
* Call पर callback न हो तो `report_progress` कुछ नहीं करता। बिना शर्त report करें।
* जब `total` पता न हो तो उसे छोड़ दें; callback को `None` मिलता है।
Progress वह है जो चलता हुआ tool **user** को दिखाता है। जो lines वह **आपके** लिए, यानी server चलाने वाले व्यक्ति के लिए log करता है, वे एक अलग channel हैं: **[Logging](logging.md)**।

View file

@ -0,0 +1,51 @@
---
translation:
sections: [5c82b20cbd65ded0, 9dc22632be79a533, 1fb8f452e990c456, 42666ab914ff0cb1, c4e0cb3667fd5ff9]
tool: 1
---
# Sampling और roots {#sampling-and-roots}
handler जुड़े हुए client से दो और चीज़ें माँग सकता है: client के अपने model से एक completion (**sampling**), और client के workspace folders (**roots**)।
दोनों अब भी काम करते हैं, उस हर protocol version पर जो SDK बोलता है। लेकिन इनके इर्द-गिर्द design बनाने से पहले यह warning पढ़ लें:
!!! warning "2026-07-28 specification में deprecated"
Sampling और roots `2026-07-28` से deprecated हैं ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/2577))। ये पूरी तरह काम करते रहेंगे और हटाए जाने योग्य होने से पहले कम से कम बारह महीने specification में बने रहेंगे, लेकिन नए implementations को इन पर नहीं बनना चाहिए। सुझाए गए migrations: sampling की जगह सीधे अपने LLM provider की API से integrate करें, और roots की जगह directories को tool parameters, resource URIs या server configuration से दें। SDK भर की सूची **[Deprecated features](../deprecated.md)** में है।
## Sampling: client का model उधार लेना {#sampling-borrow-the-clients-model}
resolver `Sample(...)` लौटाता है और tool को completion मिलता है, उसी dependency तंत्र के ज़रिए जो **[Dependencies](dependencies.md)** में `Elicit` चलाता है:
```python title="server.py" hl_lines="10-15 19"
--8<-- "docs_src/sampling_and_roots/tutorial001.py"
```
* `Sample(messages, max_tokens=...)` `sampling/createMessage` के parameters को दोहराता है। inject की गई value client का `CreateMessageResult` है; `tools` या `tool_choice` दें तो यह `CreateMessageResultWithTools` बन जाता है।
* client ने `sampling` capability declare की होनी चाहिए (अगर आप `tools` या `tool_choice` देते हैं तो `sampling.tools`)। अगर नहीं की, तो ऐसी request भेजने के बजाय जिसे client संभाल नहीं सकता, call `-32021` protocol error के साथ fail हो जाता है। बिना back-channel वाला 2026 से पहले का session अपने सामान्य no-back-channel error के साथ fail होता है, क्योंकि भेजने के लिए कोई रास्ता ही नहीं है।
* `2026-07-28` पर request multi-round-trip flow के अंदर पहुँचाई जाती है (**[Multi-round-trip requests](multi-round-trip.md)**); `2025-11-25` पर यह client को भेजी गई एक अलग request होती है। code दोनों तरह से वही रहता है, लेकिन multi-round-trip का नियम ध्यान में रखें: request हर retry round में एक जैसी बननी चाहिए, इसलिए इसे सिर्फ़ tool के arguments और दूसरे स्थिर data से ही बनाएँ।
* `include_context` को न छेड़ें: `"none"` के अलावा बाकी values खुद deprecated हैं (SEP-2596) और उन्हें ऐसी capability चाहिए जो लगभग कोई client declare नहीं करता।
## Roots: यह कहाँ जाए? {#roots-where-should-this-go}
Roots वे folders हैं जिन पर, client के अनुसार, server काम कर सकता है। ये जानकारी के लिए दिए गए मार्गदर्शन हैं, access-control का तंत्र नहीं। resolver `ListRoots()` लौटाता है:
```python title="server.py" hl_lines="10-11 15"
--8<-- "docs_src/sampling_and_roots/tutorial002.py"
```
* inject किया गया `ListRootsResult` `Root`s की एक सूची रखता है: एक `file://` URI और एक वैकल्पिक display name।
* शर्त वही है जो sampling के लिए है: declare की गई `roots` capability के बिना, request भेजने के बजाय call `-32021` के साथ fail हो जाता है।
wire के दूसरी तरफ़, client दोनों requests का जवाब उन्हीं callbacks से देता है जो उसके पास पहले से हैं: `sampling_callback` और `list_roots_callback`, जिनकी जानकारी **[Client callbacks](../client/callbacks.md)** में है।
## 2025 पीढ़ी के connections पर {#on-2025-era-connections}
`ctx.session.create_message(...)` और `ctx.session.list_roots()` उस code के लिए अब भी मौजूद हैं जो session को सीधे चलाता है। ये सिर्फ़ वहीं काम करते हैं जहाँ back-channel मौजूद है (2025 पीढ़ी के, non-stateless connections), और इन्हें call करने पर deprecation warning आती है। ऊपर दिए गए resolver markers ही समर्थित तरीका हैं: वे negotiate हुए version के हिसाब से delivery चुनते हैं और कोई warning नहीं देते।
## सारांश {#recap}
* resolver से `Sample(...)` या `ListRoots()` लौटाएँ; tool को `CreateMessageResult` या `ListRootsResult` किसी भी दूसरी dependency की तरह मिलता है।
* client को मेल खाती capability declare करनी होगी, वरना request भेजे जाने के बजाय call `-32021` के साथ fail हो जाता है।
* दोनों features `2026-07-28` पर deprecated हैं: फ़िलहाल पूरी तरह काम करते हैं, पर नए designs के लिए गलत चुनाव हैं। sampling की जगह provider APIs और roots की जगह स्पष्ट parameters को तरजीह दें।
धीमा tool कितना आगे बढ़ा, यह बताना: **[Progress](progress.md)**।

View file

@ -0,0 +1,152 @@
---
translation:
sections: [60a9de8a0bdaa531, 317bbe7e4355cdcc, a61d660c8029e04a, 8f7e82fcb88df8a9, b165db51249ff8ed, 266f56fb798068a4, 7c0e57030b622139, df18d7c2417a9883]
tool: 1
---
# Subscriptions {#subscriptions}
किसी server का catalog तय नहीं होता। tools runtime पर आ जाते हैं, और resource URI के पीछे का content बदलता रहता है।
client को इसकी खबर **subscriptions** से मिलती है। client एक `subscriptions/listen` request भेजता है, और उस request का response ही stream है: वह खुला रहता है और वही change notifications लाता है जो client ने माँगे थे।
## tool से publish करना {#publish-it-from-the-tool}
आपके हिस्से का काम बस एक line है: बदलाव publish करें।
```python title="server.py" hl_lines="20 32"
--8<-- "docs_src/subscriptions/tutorial001.py"
```
* `await ctx.notify_resource_updated("board://sprint")` हर उस खुले stream तक पहुँचता है जिसने उस URI को subscribe किया था। और किसी तक नहीं।
* `await ctx.notify_tools_changed()` हर उस stream तक पहुँचता है जिसने tool-list के बदलाव माँगे थे। जिस client को यह मिलता है वह `tools/list` दोबारा call करता है, और अब उसे `sprint_report` दिखता है।
* इसके साथी `notify_prompts_changed()` और `notify_resources_changed()` हैं।
* कोई subscriber नहीं, तो कोई काम नहीं। खाली बैठे server पर publish करना no-op है, इसलिए आपको कभी जाँचना नहीं पड़ता कि कोई सुन रहा है या नहीं। आप बस बताते हैं कि क्या बदला।
`MCPServer` आपके लिए `subscriptions/listen` serve करता है। wire की ज़िम्मेदारियाँ (पहले frame के रूप में acknowledgment, हर stream के हिसाब से filtering, हर frame पर subscription id) SDK संभालता है।
!!! check
wire पर, जिस stream के filter में `board://sprint` का नाम था वह `complete_task` चलने के बाद ऐसा दिखता है:
```json
{"method": "notifications/subscriptions/acknowledged",
"params": {"notifications": {"resourceSubscriptions": ["board://sprint"]}, "_meta": {"io.modelcontextprotocol/subscriptionId": "listen-1"}}}
{"method": "notifications/resources/updated",
"params": {"uri": "board://sprint", "_meta": {"io.modelcontextprotocol/subscriptionId": "listen-1"}}}
```
ध्यान दें कि update में क्या **नहीं** है: board। हर frame में `_meta` के नीचे listen request की JSON-RPC id होती है, और वही id subscription id है। इसे client गढ़ता है: Python का `Client` `"listen-1"` जैसी strings इस्तेमाल करता है; दूसरे clients integers इस्तेमाल कर सकते हैं।
## सिर्फ़ वही जो माँगा गया {#only-what-was-asked-for}
filter एक contract है। जिस stream ने tool-list के बदलाव और एक resource URI माँगे थे, उसे यही दो तरह की चीज़ें मिलती हैं और कुछ नहीं। कोई prompt change publish करें, तो वह stream चुप रहता है।
`MCPServer` resource URIs को हूबहू strings के रूप में मिलाता है, इसलिए जिस stream ने `board://sprint` का नाम दिया उसे `board://sprint/tasks/1` के बारे में कुछ सुनाई नहीं देता। spec server को subscribe किए गए URI के किसी sub-resource पर बदलाव बताने देता है; `MCPServer` ऐसा कभी नहीं करता, पर clients इसकी उम्मीद रखने के लिए बने होते हैं।
दो चीज़ें जो stream **नहीं** है:
* **यह replay log नहीं है।** टूटा हुआ stream चला गया, और जब कोई जुड़ा नहीं था तब publish हुए events queue में नहीं रखे जाते। clients दोबारा listen करते हैं और दोबारा fetch करते हैं।
* **यह 2025 वाला रास्ता नहीं है।** जिन clients ने `resources/subscribe` call किया था उन्हें `ctx.session.send_resource_updated(uri)` serve करता है। `notify_*` methods सिर्फ़ `subscriptions/listen` streams तक पहुँचते हैं।
## कौन देख सकता है, यह तय करना {#deciding-who-may-watch}
default रूप से हर माँगा गया kind और URI मान लिया जाता है: कोई भी caller आपके publish किए किसी भी URI को देख सकता है। कोई भी आपके read handler से नहीं पूछता, क्योंकि कोई पढ़ ही नहीं रहा — जिस caller को आपका `files://{name}` handler लौटा देता, वह भी `files://payroll.csv` पर stream खोल सकता है और जान सकता है कि वह बदली, और कब। उसे content कभी नहीं मिलता, और वह यह टटोल नहीं सकता कि क्या मौजूद है, क्योंकि अनजान URI भी मान लिया जाता है और बस कभी fire नहीं होता। खतरा छोटा है पर असली है, इसलिए multi-tenant server से हर user के अलग URIs publish करने से पहले इस पर gate लगाएँ।
यह gate एक middleware है। वह `subscriptions/listen` request को SDK के acknowledge करने से पहले देखता है, और जब caller कुछ ऐसा माँगता है जिसे पढ़ने की उसे इजाज़त नहीं, तो मना कर देता है:
```python title="server.py" hl_lines="19-26 29"
--8<-- "docs_src/subscriptions/tutorial006.py"
```
* `ctx.params` कच्ची request है, इसलिए middleware खुद उसे `SubscriptionsListenRequestParams` में validate करता है और वह filter पढ़ता है जो client ने माँगा था।
* मना करने का मतलब `call_next(ctx)` से पहले `MCPError` raise करना है: client को वह error मिलता है और कोई stream नहीं, और connection चलता रहता है। message एक जैसा रखें, किसी URI का नाम न लें, ताकि मना करने से कभी यह पक्का न हो कि कौन से URIs सुरक्षित हैं।
* एक ही `can_access(user, uri)` दोनों सवालों का जवाब देता है। resource handler उससे `resources/read` पर पूछता है; middleware उससे `subscriptions/listen` पर पूछता है। table की जगह database या अपना RBAC system रख दें, और दोनों कदम मिलाकर चलते रहते हैं।
* फ़ैसला stream के पूरे जीवनकाल तक लागू रहता है। हर event पर दोबारा जाँच नहीं होती, इसलिए अगर किसी caller की पहुँच stream के बीच में खत्म हो सकती है (expire होता token), तो जब ऐसा हो तब उस caller का connection बंद कर दें।
middleware का पूरा contract, यह और क्या-क्या wrap करता है और इसे provisional क्यों कहा गया है, यह सब **[Middleware](../advanced/middleware.md)** पर है।
## client वाला सिरा {#the-client-end}
यह रहा उस stream के दूसरी तरफ़ का client, जो board पर नज़र रख रहा है:
```python title="client.py" hl_lines="15"
--8<-- "docs_src/subscriptions/tutorial003.py"
```
`client.listen(...)` में दाख़िल होते ही request भेजी जाती है और आपके acknowledgment का इंतज़ार होता है, इसलिए block शुरू होते समय stream चालू होता है, और हर typed event दोबारा fetch करने का इशारा है, payload कभी नहीं। पूरा contract एक ही screen में बस इतना है। client वाले सिरे की बाकी हर बात अपने अलग page पर है: main flow के साथ-साथ नज़र रखना, stream का खत्म होना, और दोबारा listen करना। *Clients* के नीचे **[Subscriptions](../client/subscriptions.md)** देखें।
## एक process से आगे scale करना {#scaling-past-one-process}
publishes आपके handler से खुले streams तक `SubscriptionBus` के ज़रिए पहुँचते हैं। default in-memory है: एक process, उसके अंदर का हर stream। यही सही जवाब है जब तक आप load balancer के पीछे replicas नहीं चलाते, क्योंकि तब client का stream एक replica से बँध जाता है, और किसी दूसरे replica पर हुए publish को उस तक पहुँचना होता है।
यह जोड़ आपको implement करना है: आपके pub/sub backend के ऊपर दो methods।
```python
from collections.abc import Callable
from redis.asyncio import Redis
from mcp.server.mcpserver import MCPServer
from mcp.server.subscriptions import ServerEvent # SubscriptionBus is a Protocol: no base class
class RedisSubscriptionBus:
def __init__(self, redis: Redis) -> None:
self._redis = redis
self._listeners: dict[object, Callable[[ServerEvent], None]] = {}
async def publish(self, event: ServerEvent) -> None:
await self._redis.publish("mcp-events", encode(event)) # to every replica
def subscribe(self, listener: Callable[[ServerEvent], None]) -> Callable[[], None]:
token = object()
self._listeners[token] = listener
def unsubscribe() -> None:
self._listeners.pop(token, None)
return unsubscribe
mcp = MCPServer("Sprint Board", subscriptions=RedisSubscriptionBus(redis))
```
`encode` आपका है, और हर replica पर वह reader task भी आपका है जो आने वाले messages को decode करता है और हर registered listener को call करता है। listeners synchronous होते हैं, उन्हें raise करना मना है, और वे server के event loop पर चलते हैं।
bus typed `ServerEvent` values ले जाता है, चार छोटी dataclasses, JSON-RPC कभी नहीं। stamping, filtering, और stream lifecycles SDK में ही रहते हैं, इसलिए bus का कोई implementation protocol नहीं तोड़ सकता। वह सिर्फ़ events को processes के बीच पहुँचा सकता है।
request के बाहर से publish करने के लिए bus खुद बनाएँ ताकि reference आपके पास रहे। जब आप कुछ pass नहीं करते तो `MCPServer` अंदर ही अंदर एक बना लेता है, और उसे बाहर नहीं दिखाता।
```python
from mcp.server.subscriptions import InMemorySubscriptionBus, ToolsListChanged
bus = InMemorySubscriptionBus()
mcp = MCPServer("Sprint Board", subscriptions=bus)
async def tools_reloaded() -> None:
await bus.publish(ToolsListChanged()) # from a lifespan task, a webhook, anywhere
```
## Low-level composition {#the-low-level-composition}
low-level `Server` पर पहले से कुछ भी जुड़ा हुआ नहीं है, और वही हिस्से तीन lines में जुड़ जाते हैं:
```python title="server.py" hl_lines="8-9 47"
--8<-- "docs_src/subscriptions/tutorial002.py"
```
* bus आपका है, इसलिए आप सीधे उस पर publish करते हैं: `await bus.publish(ResourceUpdated(uri=...))`। उसे वहाँ रखें जहाँ आपके handlers उस तक पहुँच सकें: यहाँ module scope में, बड़े app में lifespan में।
* `ListenHandler(bus)` वही handler है जो `MCPServer` register करता है, और `on_subscriptions_listen=` एक साधारण handler slot है। अलग semantics के लिए उस slot में अपना callable रखें, और spec की ज़िम्मेदारियाँ आप पर आ जाती हैं: पहले acknowledge करें, हर frame पर subscription id की मुहर लगाएँ, filter के बाहर कुछ भी न भेजें।
* `ListenHandler.close()` हर खुले stream को सलीके से खत्म करता है। हर एक को अपने आख़िरी frame के रूप में listen request का result मिलता है, जो spec का यह कहने का तरीका है कि server ने subscription जान-बूझकर खत्म किया। यह उन streams के flush पूरा करने से पहले लौट आता है, इसलिए transport गिराने से पहले उन्हें एक पल दें। इसके बिना, streams तब खत्म होते हैं जब client disconnect करता है।
## सारांश {#recap}
* client एक `subscriptions/listen` request से शामिल होता है, और response ही stream है। इसे serve करना पहले से बना हुआ है।
* आप `ctx.notify_*` से publish करते हैं, और stamping, filtering, और lifecycle का काम SDK करता है।
* events इशारे हैं, payloads नहीं। दोनों सिरे दोबारा fetch करते हैं।
* client वाला सिरा `async with client.listen(...)` है: उसकी कहानी *Clients* के नीचे **[Subscriptions](../client/subscriptions.md)** में है।
* low-level `Server` पर आप वही हिस्से खुद जोड़ते हैं: एक bus, `ListenHandler(bus)`, `on_subscriptions_listen` slot।
* scale out करने का मतलब है `SubscriptionBus` implement करना, बस दो methods, और उसे `MCPServer(subscriptions=...)` के रूप में pass करना।
यह सब serve करने वाले server को चलाना, एक replica के पीछे हो या बीस के, **[Deploy और scale](../run/deploy.md)** में है।