Merge pull request modelcontextprotocol#21 from modelcontextprotocol/davidsp/concepts

Python version of the concepts pages

Author: dsp-ant

docs/concepts/architecture.mdx

@@ -56,7 +56,37 @@ The protocol layer handles message framing, request/response linking, and high-l
   </Tab>
   <Tab title="Python">
     ```python
-    # Python implementation coming soon
+    class Session(BaseSession[RequestT, NotificationT, ResultT]):
+        async def send_request(
+            self,
+            request: RequestT,
+            result_type: type[Result]
+        ) -> Result:
+            """
+            Send request and wait for response. Raises McpError if response contains error.
+            """
+            # Request handling implementation
+
+        async def send_notification(
+            self,
+            notification: NotificationT
+        ) -> None:
+            """Send one-way notification that doesn't expect response."""
+            # Notification handling implementation
+
+        async def _received_request(
+            self,
+            responder: RequestResponder[ReceiveRequestT, ResultT]
+        ) -> None:
+            """Handle incoming request from other side."""
+            # Request handling implementation
+
+        async def _received_notification(
+            self,
+            notification: ReceiveNotificationT
+        ) -> None:
+            """Handle incoming notification from other side."""
+            # Notification handling implementation
     ```
   </Tab>
 </Tabs>
@@ -212,7 +242,32 @@ Here's a basic example of implementing an MCP server:
   </Tab>
   <Tab title="Python">
     ```python
-    # Python implementation coming soon
+    import asyncio
+    import mcp.types as types
+    from mcp.server import Server
+    from mcp.server.stdio import stdio_server
+
+    app = Server("example-server")
+
+    @app.list_resources()
+    async def list_resources() -> list[types.Resource]:
+        return [
+            types.Resource(
+                uri="example://resource",
+                name="Example Resource"
+            )
+        ]
+
+    async def main():
+        async with stdio_server() as streams:
+            await app.run(
+                streams[0],
+                streams[1],
+                app.create_initialization_options()
+            )
+
+    if __name__ == "__main__":
+        asyncio.run(main)
     ```
   </Tab>
 </Tabs>

docs/concepts/prompts.mdx

@@ -292,7 +292,85 @@ Here's a complete example of implementing prompts in an MCP server:
   </Tab>
   <Tab title="Python">
     ```python
-    # Python implementation coming soon
+    from mcp.server import Server
+    import mcp.types as types
+
+    # Define available prompts
+    PROMPTS = {
+        "git-commit": types.Prompt(
+            name="git-commit",
+            description="Generate a Git commit message",
+            arguments=[
+                types.PromptArgument(
+                    name="changes",
+                    description="Git diff or description of changes",
+                    required=True
+                )
+            ],
+        ),
+        "explain-code": types.Prompt(
+            name="explain-code",
+            description="Explain how code works",
+            arguments=[
+                types.PromptArgument(
+                    name="code",
+                    description="Code to explain",
+                    required=True
+                ),
+                types.PromptArgument(
+                    name="language",
+                    description="Programming language",
+                    required=False
+                )
+            ],
+        )
+    }
+
+    # Initialize server
+    app = Server("example-prompts-server")
+
+    @app.list_prompts()
+    async def list_prompts() -> list[types.Prompt]:
+        return list(PROMPTS.values())
+
+    @app.get_prompt()
+    async def get_prompt(
+        name: str, arguments: dict[str, str] | None = None
+    ) -> types.GetPromptResult:
+        if name not in PROMPTS:
+            raise ValueError(f"Prompt not found: {name}")
+
+        if name == "git-commit":
+            changes = arguments.get("changes") if arguments else ""
+            return types.GetPromptResult(
+                messages=[
+                    types.PromptMessage(
+                        role="user",
+                        content=types.TextContent(
+                            type="text",
+                            text=f"Generate a concise but descriptive commit message "
+                            f"for these changes:\n\n{changes}"
+                        )
+                    )
+                ]
+            )
+
+        if name == "explain-code":
+            code = arguments.get("code") if arguments else ""
+            language = arguments.get("language", "Unknown") if arguments else "Unknown"
+            return types.GetPromptResult(
+                messages=[
+                    types.PromptMessage(
+                        role="user",
+                        content=types.TextContent(
+                            type="text",
+                            text=f"Explain how this {language} code works:\n\n{code}"
+                        )
+                    )
+                ]
+            )
+
+        raise ValueError("Prompt implementation not found")
     ```
   </Tab>
 </Tabs>

docs/concepts/resources.mdx

@@ -186,7 +186,33 @@ Here's a simple example of implementing resource support in an MCP server:
   </Tab>
   <Tab title="Python">
     ```python
-    # Python implementation coming soon
+    app = Server("example-server")
+
+    @app.list_resources()
+    async def list_resources() -> list[types.Resource]:
+        return [
+            types.Resource(
+                uri="file:///logs/app.log",
+                name="Application Logs",
+                mimeType="text/plain"
+            )
+        ]
+
+    @app.read_resource()
+    async def read_resource(uri: AnyUrl) -> str:
+        if str(uri) == "file:///logs/app.log":
+            log_contents = await read_log_file()
+            return log_contents
+
+        raise ValueError("Resource not found")
+
+    # Start server
+    async with stdio_server() as streams:
+        await app.run(
+            streams[0],
+            streams[1],
+            app.create_initialization_options()
+        )
     ```
   </Tab>
 </Tabs>

docs/concepts/tools.mdx

@@ -82,7 +82,36 @@ Here's an example of implementing a basic tool in an MCP server:
   </Tab>
   <Tab title="Python">
     ```python
-    # Python implementation coming soon
+    app = Server("example-server")
+
+    @app.list_tools()
+    async def list_tools() -> list[types.Tool]:
+        return [
+            types.Tool(
+                name="calculate_sum",
+                description="Add two numbers together",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "a": {"type": "number"},
+                        "b": {"type": "number"}
+                    },
+                    "required": ["a", "b"]
+                }
+            )
+        ]
+
+    @app.call_tool()
+    async def call_tool(
+        name: str,
+        arguments: dict
+    ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
+        if name == "calculate_sum":
+            a = arguments["a"]
+            b = arguments["b"]
+            result = a + b
+            return [types.TextContent(type="text", text=str(result))]
+        raise ValueError(f"Tool not found: {name}")
     ```
   </Tab>
 </Tabs>
@@ -212,30 +241,59 @@ Tool errors should be reported within the result object, not as MCP protocol-lev
 
 Here's an example of proper error handling for tools:
 
-```typescript
-try {
-  // Tool operation
-  const result = performOperation();
-  return {
-    content: [
-      {
-        type: "text",
-        text: `Operation successful: ${result}`
-      }
-    ]
-  };
-} catch (error) {
-  return {
-    isError: true,
-    content: [
-      {
-        type: "text",
-        text: `Error: ${error.message}`
-      }
-    ]
-  };
-}
-```
+<Tabs>
+  <Tab title="TypeScript">
+    ```typescript
+    try {
+      // Tool operation
+      const result = performOperation();
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Operation successful: ${result}`
+          }
+        ]
+      };
+    } catch (error) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Error: ${error.message}`
+          }
+        ]
+      };
+    }
+    ```
+  </Tab>
+  <Tab title="Python">
+    ```python
+    try:
+        # Tool operation
+        result = perform_operation()
+        return types.CallToolResult(
+            content=[
+                types.TextContent(
+                    type="text",
+                    text=f"Operation successful: {result}"
+                )
+            ]
+        )
+    except Exception as error:
+        return types.CallToolResult(
+            isError=True,
+            content=[
+                types.TextContent(
+                    type="text",
+                    text=f"Error: {str(error)}"
+                )
+            ]
+        )
+    ```
+  </Tab>
+</Tabs>
 
 This approach allows the LLM to see that an error occurred and potentially take corrective action or request human intervention.