{ "swagger": "2.0", "info": { "title": "O'Reilly Expert MCP Server", "version": "", "description": "This document provides a technical overview of the O'Reilly Expert MCP (Model Context Protocol) Server.\nThe Expert MCP server endpoint is: https://api.oreilly.com/api/expert/v1/mcp\n\nIn addition to `search_oreilly_content`, which supports keyword searches with optional filters\nsuch as content type, language and author, Expert MCP provides `ask_oreilly_experts` and\n`get_oreilly_citation`, which answer specific technical questions by retrieving grounded, citable\nsnippets from O'Reilly's expert-authored library, rather than returning a list of titles to browse.\n\nExpert MCP is a paid, enterprise-oriented add-on. See [Access & Entitlement](#section/Access-and-Entitlement)\nbelow for what that means for connecting clients, and the\n[O'Reilly MCP Guide](https://www.oreilly.com/online-learning/support/mcp-guide.html) for\nend-to-end setup instructions aimed at account administrators.\n\n## Access & Entitlement\n\nAccess to Expert MCP requires the Expert MCP entitlement on your O'Reilly account. This is\ndistinct from having valid credentials: a user can authenticate successfully (via OAuth or a\npersonal access token) and still be refused access if their account isn't entitled.\n\nUnentitled connections are rejected outright rather than given a reduced tool list — every request\nto the Expert MCP endpoint returns an HTTP `403` until the account carries the entitlement:\n\n```json\n{\n \"error\": \"forbidden\",\n \"error_description\": \"The 'xmcp' (Expert MCP) permission is required.\"\n}\n```\n\nIf you're seeing this error:\n\n- Individual users should confirm with their O'Reilly account administrator that Expert MCP has\n been enabled for their account.\n\n- Account administrators can find setup and entitlement instructions in the\n [O'Reilly MCP Guide](https://www.oreilly.com/online-learning/support/mcp-guide.html).\n\n## Authentication\n\nAll requests to this API require authentication and no anonymous requests are permitted.\nThe server supports OAuth Dynamic Client Registration (DCR) and token authentication.\nStatic client credentials are not currently supported. Authenticating successfully is necessary\nbut not sufficient — see [Access & Entitlement](#section/Access-and-Entitlement) above.\n\n### OAuth\n\nClients such as Claude Code, Cursor, and VS Code will automatically use OAuth if a token is\nnot provided in the configuration.\n\nUpon connection to the server an `Application Access Request` page will open in the browser.\nThe page will display the application being used and the local location of that application.\nTo continue click `Allow Access`, you will then be prompted to login with your O'Reilly account\ncredentials. Upon logging in credentials will be sent to the client and the connection\nwill be established.\n\n#### Claude Code\n\nFrom the command line, run the following command:\n\n```bash\nclaude mcp add --transport http oreilly https://api.oreilly.com/api/expert/v1/mcp\n```\n\nServers are added at `local` scope by default, which registers `oreilly` only for the directory\nyou ran the command in. Pass `--scope user` to make it available across all of your projects:\n\n```bash\nclaude mcp add --scope user --transport http oreilly https://api.oreilly.com/api/expert/v1/mcp\n```\n\nAfter starting Claude Code with the `claude` command, you can run the `/mcp` slash command to\nsee the connection and authentication status.\n\nTo authenticate with the server, select the `oreilly` server from the list of MCP servers\nusing the arrow keys and press enter. You can then select `Authenticate` to begin the OAuth flow.\n\n#### Cursor\n\nNavigate to Settings -> Cursor Settings -> Tools & MCPs\n\nClick New MCP Server\n\nAdd the following to your mcp.json file:\n\n```json\n{\n \"mcpServers\": {\n \"oreilly\": {\n \"url\": \"https://api.oreilly.com/api/expert/v1/mcp\"\n }\n }\n}\n```\n\n#### VS Code\n\nNote: the trailing slash is not included in the URL.\n\n```json\n{\n \"servers\": {\n \"oreilly\": {\n \"type\": \"http\",\n \"url\": \"https://api.oreilly.com/api/expert/v1/mcp\"\n }\n }\n}\n```\n\n### Token Authentication\n\nTokens serve as an identifier and provide authorization to communicate with the server. The\ntoken will be used to perform permissions based filtering on content results returned by the\ntool(s), and to check the Expert MCP entitlement described above — if the account the token\nbelongs to isn't entitled, requests will be rejected regardless of the token's validity.\n\nYou can generate a personal access token by going to the [MCP Tokens page](https://learning.oreilly.com/access-tokens/) under the Profile menu.\nYou can create multiple access tokens if you plan to use the MCP server in more than one tool and access tokens can be revoked at any time.\n\nAccount administrators provision Expert MCP access and generate tokens for their organization from\nthe Content MCP token option on the [API Tokens page](https://learning.oreilly.com/integrations/api-tokens/)\nunder the Integrations section of the Admin Console. For a complete walkthrough of enterprise setup —\nincluding assigning the Expert MCP entitlement to users and generating tokens on their behalf — see\nthe [O'Reilly MCP Guide](https://www.oreilly.com/online-learning/support/mcp-guide.html).\n\nInclude your token in the Authorization header:\n\n```\nAuthorization: Bearer {YOUR_TOKEN}\n```\n\nBe sure to replace `{YOUR_TOKEN}` with your actual token.\n\n#### Claude Code\n\nFrom the command line, run the following command:\n\n```bash\nclaude mcp add --transport http oreilly https://api.oreilly.com/api/expert/v1/mcp \\\n --header \"Authorization: Bearer {YOUR_TOKEN}\"\n```\n\nAs with OAuth, this registers `oreilly` only for the directory you ran the command in. Add `--scope user` to make it available across all of your projects.\n\nAfter starting Claude Code with the `claude` command, you can run the `/mcp` slash command to see the connection and authentication status.\n\n#### Cursor\n\nNavigate to Settings -> Cursor Settings -> Tools & MCPs\n\nClick New MCP Server\n\nAdd the following to your mcp.json file:\n\n```json\n{\n \"mcpServers\": {\n \"oreilly\": {\n \"url\": \"https://api.oreilly.com/api/expert/v1/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer {YOUR_TOKEN}\"\n }\n }\n }\n}\n```\n\n#### VS Code\n\n```json\n{\n \"servers\": {\n \"oreilly\": {\n \"type\": \"http\",\n \"url\": \"https://api.oreilly.com/api/expert/v1/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${input:oreilly_expert_mcp_token}\"\n }\n }\n },\n \"inputs\": [\n {\n \"type\": \"promptString\",\n \"id\": \"oreilly_expert_mcp_token\",\n \"description\": \"O'Reilly Expert MCP Token\",\n \"password\": true\n }\n ]\n}\n```\n\nUpon starting the MCP server, the user will be prompted to enter their token, it will then be stored in the VS Code settings and used for future connections.\n\n## Python Client Example\n\nBelow is a minimal Python client example using the official MCP SDK to connect to the server, list\nits tools, and call `ask_oreilly_experts` followed by `get_oreilly_citation`:\n\n```python\nimport os\nfrom mcp.client.session import ClientSession\nfrom mcp.client.streamable_http import streamablehttp_client\n\nMCP_URL = \"https://api.oreilly.com/api/expert/v1/mcp\"\n\nasync def main():\n my_token = os.environ.get(\"OREILLY_EXPERT_MCP_TOKEN\")\n headers = {\"Authorization\": f\"Bearer {my_token}\"}\n\n async with streamablehttp_client(MCP_URL, headers=headers) as streams:\n async with ClientSession(streams[0], streams[1]) as session:\n await session.initialize()\n\n # List available tools\n tools = await session.list_tools()\n print(\"Available tools:\", tools)\n\n # Ask a technical question against the expert library\n answer = await session.call_tool(\n \"ask_oreilly_experts\",\n {\n \"question\": \"What is a pytest fixture?\",\n }\n )\n print(\"Expert results:\", answer)\n\n # Retrieve the full text of a high-scoring snippet for citation.\n #\n # The product_id/offset below are hardcoded for illustration only, and\n # will likely fail as-is: get_oreilly_citation only accepts pairs\n # returned by an ask_oreilly_experts call. Results change as the\n # library is updated, so read product_id and offset out of your own\n # `answer` above rather than copying these values.\n citation = await session.call_tool(\n \"get_oreilly_citation\",\n {\n \"product_id\": \"9781098139575\",\n \"offset\": 662,\n }\n )\n print(\"Citation:\", citation)\n\nif __name__ == \"__main__\":\n import asyncio\n asyncio.run(main())\n```\n\n**Requirements:**\n\n```bash\npip install mcp\n```\n\n**Note:** The MCP Python SDK and other official MCP libraries handle the JSON-RPC protocol formatting automatically.\nYou don't need to manually construct the `jsonrpc`, `method`, and `params` fields shown in the protocol documentation below when\nusing a language MCP SDK." }, "host": "api.oreilly.com", "basePath": "/", "schemes": [ "https" ], "paths": { "/api/expert/v1/mcp": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "examples": { "application/json": { "jsonrpc": "2.0", "result": { "protocolVersion": "2025-06-18", "capabilities": { "tools": { "listChanged": false }, "experimental": {} }, "serverInfo": { "name": "mcp-content-discovery-expert", "version": "1.15.0" } }, "id": 0 } }, "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "result": { "type": "object", "properties": { "protocolVersion": { "type": "string", "description": "MCP protocol version supported by server" }, "capabilities": { "type": "object", "properties": { "tools": { "type": "object", "properties": { "listChanged": { "type": "boolean", "description": "Whether the tools list can change" } }, "required": [ "listChanged" ], "additionalProperties": false, "description": "Tools-related capabilities" }, "experimental": { "type": "object", "properties": {}, "description": "Experimental capabilities" } }, "required": [ "tools" ], "additionalProperties": false, "description": "Server capabilities" }, "serverInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "Server name" }, "version": { "type": "string", "description": "Server version" } }, "required": [ "name", "version" ], "additionalProperties": false, "description": "Information about the server" } }, "required": [ "protocolVersion", "capabilities", "serverInfo" ], "additionalProperties": false, "description": "Initialization result" }, "id": { "type": "number", "description": "Request identifier matching the request" } }, "required": [ "jsonrpc", "result", "id" ], "additionalProperties": false } }, "403": { "description": "Forbidden", "headers": {}, "examples": { "application/json": { "error": "forbidden", "error_description": "The 'xmcp' (Expert MCP) permission is required." } }, "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "example": { "error": "forbidden", "error_description": "The 'xmcp' (Expert MCP) permission is required." } } } }, "summary": "Initialize Session", "operationId": "Initialize Session", "description": "Initialize the MCP session and negotiate protocol version and capabilities. The initialization process consists of two steps:\n\n1. Client sends `initialize` request and receives server capabilities\n\n2. Client sends `notifications/initialized` to confirm readiness\n\nThis must be completed before any other methods can be called.\n\n**Step 1: Initialize Request**", "tags": [ "MCP Endpoint" ], "parameters": [ { "name": "Accept", "in": "header", "description": "e.g. application/json, text/event-stream", "required": false, "x-example": "application/json, text/event-stream", "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "method": { "type": "string", "description": "MCP method to invoke" }, "params": { "type": "object", "properties": { "protocolVersion": { "type": "string", "description": "MCP protocol version" }, "capabilities": { "type": "object", "properties": {}, "description": "Client capabilities (can be empty object)" }, "clientInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "Client name" }, "version": { "type": "string", "description": "Client version" } }, "required": [ "name", "version" ], "additionalProperties": false, "description": "Information about the client" } }, "required": [ "protocolVersion", "capabilities", "clientInfo" ], "additionalProperties": false, "description": "Initialization parameters" }, "id": { "type": "number", "description": "Request identifier" } }, "required": [ "jsonrpc", "method", "params", "id" ], "additionalProperties": false, "example": { "jsonrpc": "2.0", "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "mcp", "version": "0.1.0" } }, "id": 0 } } } ], "produces": [ "application/json" ], "consumes": [ "application/json" ], "security": [ { "oauth2": [] } ] } }, "/api/expert/v1/mcp ": { "post": { "responses": { "202": { "description": "Accepted", "headers": {}, "examples": {} }, "403": { "description": "Forbidden", "headers": {}, "examples": { "application/json": { "error": "forbidden", "error_description": "The 'xmcp' (Expert MCP) permission is required." } }, "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "example": { "error": "forbidden", "error_description": "The 'xmcp' (Expert MCP) permission is required." } } } }, "summary": "Send Initialized Notification", "operationId": "Send Initialized Notification", "description": "**Step 2: Initialized Notification**\n\nAfter receiving the initialize response, the client must send an `initialized` notification to confirm it's ready to proceed.", "tags": [ "MCP Endpoint" ], "parameters": [ { "name": "Accept", "in": "header", "description": "e.g. application/json, text/event-stream", "required": false, "x-example": "application/json, text/event-stream", "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "method": { "type": "string", "description": "Notification method (no id field since this is a notification, not a request)" } }, "required": [ "jsonrpc", "method" ], "additionalProperties": false, "example": { "jsonrpc": "2.0", "method": "notifications/initialized" } } } ], "produces": [ "application/json" ], "consumes": [ "application/json" ], "security": [ { "oauth2": [] } ] } }, "/api/expert/v1/mcp ": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "examples": { "application/json": { "jsonrpc": "2.0", "result": { "tools": [ { "name": "search_oreilly_content", "description": "This tool performs a more traditional keyword search against an index containing content on the O'Reilly learning platform and returns a list of matches and associated metadata...", "inputSchema": { "type": "object", "required": [], "properties": { "query": { "type": "string", "description": "The query to perform a search for (default: '*', max 500 characters)" }, "n_items": { "type": "integer", "description": "Number of items to return (default: 5" }, "content_types": { "type": "array", "items": { "type": "string", "enum": [ "articles", "books", "videos", "courses", "interactive", "certifications", "audiobooks", "playlists", "live-events", "skill-plan" ] }, "description": "Content types to filter by" } } } }, { "name": "ask_oreilly_experts", "description": "Search O'Reilly's expert-authored learning library for trustworthy guidance on programming, software engineering, and technology decisions...", "inputSchema": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "description": "The question to search for." }, "context": { "type": "string", "description": "Context about what the user is working on or trying to achieve." }, "author": { "type": "string", "description": "Restrict results to works by this author." } } } }, { "name": "get_oreilly_citation", "description": "Retrieve the full, citable source text of a snippet identified by ask_oreilly_experts...", "inputSchema": { "type": "object", "required": [ "product_id", "offset" ], "properties": { "product_id": { "type": "string", "description": "The product ID from search results (required)" }, "offset": { "type": "integer", "description": "The snippet offset from search results" } } } } ] }, "id": 1 } }, "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "result": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Tool name" }, "description": { "type": "string", "description": "Tool description" }, "inputSchema": { "type": "object", "properties": {}, "description": "JSON Schema defining the tool's input parameters" } }, "required": [ "name", "description", "inputSchema" ] }, "description": "Array of available tools" } }, "required": [ "tools" ], "additionalProperties": false, "description": "List of available tools" }, "id": { "type": "number", "description": "Request identifier matching the request" } }, "required": [ "jsonrpc", "result", "id" ], "additionalProperties": false } }, "403": { "description": "Forbidden", "headers": {}, "examples": { "application/json": { "error": "forbidden", "error_description": "The 'xmcp' (Expert MCP) permission is required." } }, "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "example": { "error": "forbidden", "error_description": "The 'xmcp' (Expert MCP) permission is required." } } } }, "summary": "List Available Tools", "operationId": "List Available Tools", "description": "Retrieve the list of tools available on this MCP server. Returns tool metadata including names, descriptions, and input schemas.\nThe example response below is abridged — each tool's complete parameter list is documented in the\n[Available Tools](#tag/Available-Tools) section above, and in the request schema of its\ncorresponding **Call ... Tool** section below.", "tags": [ "MCP Endpoint" ], "parameters": [ { "name": "Accept", "in": "header", "description": "e.g. application/json, text/event-stream", "required": false, "x-example": "application/json, text/event-stream", "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "method": { "type": "string", "description": "MCP method to invoke" }, "id": { "type": "number", "description": "Request identifier" } }, "required": [ "jsonrpc", "method", "id" ], "additionalProperties": false, "example": { "jsonrpc": "2.0", "method": "tools/list", "id": 1 } } } ], "produces": [ "application/json" ], "consumes": [ "application/json" ], "security": [ { "oauth2": [] } ] } }, "/api/expert/v1/mcp ": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "examples": { "application/json": { "jsonrpc": "2.0", "result": { "content": [ { "type": "text", "text": "{\"search_results\": {\"urn:orm:book:9781098156664\": {\"publisher_names\": [\"No Starch Press\"], \"ourn\": \"urn:orm:book:9781098156664\", \"display_format\": \"book\", \"publication_date\": \"2023-01-10\", \"authors\": [\"Eric Matthes\"], \"title\": \"Python Crash Course, 3rd Edition\", \"live_event_start_dates\": null, \"page_count\": 552, \"marketing_type\": \"book\", \"duration\": null, \"url\": \"https://learning.oreilly.com/library/view/-/9781098156664/?orm_source=mcp\", \"tags\": [], \"image_url\": \"https://learning.oreilly.com/covers/9781098156664/\", \"relevance_score\": 0.8407513601845881}, ...}}" } ], "isError": false }, "id": 2 } }, "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "result": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Content type, always `text` for this tool" }, "text": { "type": "string", "description": "JSON-encoded string. Parse it to get an object with a `search_results` key, whose values are content items keyed by ourn — see the **Search Results** metadata list under [`search_oreilly_content`](#tag/Available-Tools/search_oreilly_content) above for the per-item fields." } }, "required": [ "type", "text" ] }, "description": "Array of content items returned by the tool" }, "isError": { "type": "boolean", "description": "Indicates if the result is an error" } }, "required": [ "content", "isError" ], "additionalProperties": false, "description": "The result of the tool call" }, "id": { "type": "number", "description": "Request identifier matching the request" } }, "required": [ "jsonrpc", "result", "id" ], "additionalProperties": false } }, "400": { "description": "Bad Request", "headers": {}, "examples": { "application/json": { "jsonrpc": "2.0", "error": { "code": -32602, "message": "Invalid params" }, "id": 1 } }, "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "error": { "type": "object", "properties": { "code": { "type": "number", "description": "JSON-RPC error code" }, "message": { "type": "string", "description": "Error message" }, "data": { "type": "object", "properties": {}, "description": "Additional error details" } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Error details" }, "id": { "type": "number", "description": "Request identifier matching the request" } }, "required": [ "jsonrpc", "error", "id" ], "additionalProperties": false } }, "401": { "description": "Unauthorized", "headers": {}, "examples": { "application/json": { "jsonrpc": "2.0", "error": { "code": -32602, "message": "Invalid params" }, "id": 1 } }, "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "error": { "type": "object", "properties": { "code": { "type": "number", "description": "JSON-RPC error code" }, "message": { "type": "string", "description": "Error message" }, "data": { "type": "object", "properties": {}, "description": "Additional error details" } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Error details" }, "id": { "type": "number", "description": "Request identifier matching the request" } }, "required": [ "jsonrpc", "error", "id" ], "additionalProperties": false } }, "403": { "description": "Forbidden", "headers": {}, "examples": { "application/json": { "error": "forbidden", "error_description": "The 'xmcp' (Expert MCP) permission is required." } }, "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "example": { "error": "forbidden", "error_description": "The 'xmcp' (Expert MCP) permission is required." } } } }, "summary": "Call Content Search Tool", "operationId": "Call Content Search Tool", "description": "Execute an MCP tool by sending a JSON-RPC 2.0 formatted request. The tool name and arguments are specified in the request body.", "tags": [ "MCP Endpoint" ], "parameters": [ { "name": "Accept", "in": "header", "description": "e.g. application/json, text/event-stream", "required": false, "x-example": "application/json, text/event-stream", "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "method": { "type": "string", "description": "MCP method to invoke" }, "params": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the tool to call" }, "arguments": { "type": "object", "properties": { "query": { "type": "string", "description": "The query to perform a search for. Default: `*`. Maximum 500 characters." }, "n_items": { "type": "number", "description": "Number of items to return. Default: 5." }, "languages": { "type": "array", "items": { "type": "string", "enum": [ "en", "nl", "fr", "de", "it", "ja", "ko", "pl", "pt", "es", "ru", "zh" ] }, "description": "Languages to filter by. Default: `[\"en\"]`" }, "content_types": { "type": "array", "items": { "type": "string", "enum": [ "articles", "books", "videos", "courses", "interactive", "certifications", "audiobooks", "playlists", "live" ] }, "description": "Content types to filter by. Default: all content types." }, "publisher_filter": { "type": "array", "items": { "type": "string" }, "description": "Publishers to filter by. Default: none (all publishers)." }, "author_filter": { "type": "array", "items": { "type": "string" }, "description": "Authors to filter by. Default: none (all authors)." }, "order_by": { "type": "string", "enum": [ "relevance", "popularity", "rating", "date_added", "date_published", "last_updated", "upcoming_events" ], "description": "Field to order search results by. Omit this parameter unless user specifically requests ordering." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction. For dates, `desc` shows newer/upcoming content first, `asc` shows older content first. Default: `desc`." } }, "additionalProperties": false, "description": "Tool-specific arguments" } }, "required": [ "name", "arguments" ], "additionalProperties": false, "description": "Parameters for the tool call" }, "id": { "type": "number", "description": "Request identifier" } }, "required": [ "jsonrpc", "method", "params", "id" ], "additionalProperties": false, "example": { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "search_oreilly_content", "arguments": { "query": "Python machine learning", "n_items": 5, "content_types": [ "books", "videos" ], "sort_order": "desc" } }, "id": 2 } } } ], "produces": [ "application/json" ], "consumes": [ "application/json" ], "security": [ { "oauth2": [] } ] } }, "/api/expert/v1/mcp ": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "examples": { "application/json": { "jsonrpc": "2.0", "result": { "content": [ { "type": "text", "text": "{\"results\": {\"query\": \"What is a pytest fixture?\", \"results\": [{\"product_id\": \"9781098139575\", \"product_title\": \"Hypermodern Python Tooling\", \"authors\": \"Claudio Jolowicz\", \"offset\": 662, \"snippet_preview\": \"Tests (and fixtures) can use a fixture by including a function parameter with the same name. When pytest invokes the test function, it passes the return value of the fixture function. Let’s rewrite Example 6-4 to use the fixture:\", \"published_date\": \"2024-06-18\", \"child_title\": \"6. Testing with pytest\", \"url\": \"https://learning.oreilly.com/library/view/-/9781098139575/ch06.html?orm_source=mcp\", \"relevance_score\": 0.77, \"ourn\": \"urn:orm:book:9781098139575\", \"chapter_ourn\": \"urn:orm:book:9781098139575:chapter:ch06.html\"}, ...], \"citation_format\": \"Use markdown links: [product_title](url) by authors\"}}" } ], "isError": false }, "id": 3 } }, "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "result": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Content type, always `text` for this tool" }, "text": { "type": "string", "description": "JSON-encoded string. Parse it to get an object with a `results` key containing `query`, a `citation_format` template, and a `results` array of matching snippets — see the **Response** list under [`ask_oreilly_experts`](#tag/Available-Tools/ask_oreilly_experts) above for the per-snippet fields." } }, "required": [ "type", "text" ] }, "description": "Array of content items returned by the tool" }, "isError": { "type": "boolean", "description": "Indicates if the result is an error" } }, "required": [ "content", "isError" ], "additionalProperties": false, "description": "The result of the tool call" }, "id": { "type": "number", "description": "Request identifier matching the request" } }, "required": [ "jsonrpc", "result", "id" ], "additionalProperties": false } }, "400": { "description": "Bad Request", "headers": {}, "examples": { "application/json": { "jsonrpc": "2.0", "error": { "code": -32602, "message": "Invalid params" }, "id": 1 } }, "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "error": { "type": "object", "properties": { "code": { "type": "number", "description": "JSON-RPC error code" }, "message": { "type": "string", "description": "Error message" }, "data": { "type": "object", "properties": {}, "description": "Additional error details" } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Error details" }, "id": { "type": "number", "description": "Request identifier matching the request" } }, "required": [ "jsonrpc", "error", "id" ], "additionalProperties": false } }, "401": { "description": "Unauthorized", "headers": {}, "examples": { "application/json": { "jsonrpc": "2.0", "error": { "code": -32602, "message": "Invalid params" }, "id": 1 } }, "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "error": { "type": "object", "properties": { "code": { "type": "number", "description": "JSON-RPC error code" }, "message": { "type": "string", "description": "Error message" }, "data": { "type": "object", "properties": {}, "description": "Additional error details" } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Error details" }, "id": { "type": "number", "description": "Request identifier matching the request" } }, "required": [ "jsonrpc", "error", "id" ], "additionalProperties": false } }, "403": { "description": "Forbidden", "headers": {}, "examples": { "application/json": { "error": "forbidden", "error_description": "The 'xmcp' (Expert MCP) permission is required." } }, "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "example": { "error": "forbidden", "error_description": "The 'xmcp' (Expert MCP) permission is required." } } } }, "summary": "Call Ask Experts Tool", "operationId": "Call Ask Experts Tool", "description": "Ask a technical question against O'Reilly's expert-authored library. Each result carries a\n`relevance_score` and a short `snippet_preview` rather than full text — call\n`get_oreilly_citation` with the `product_id` and `offset` for the full snippet text.", "tags": [ "MCP Endpoint" ], "parameters": [ { "name": "Accept", "in": "header", "description": "e.g. application/json, text/event-stream", "required": false, "x-example": "application/json, text/event-stream", "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "method": { "type": "string", "description": "MCP method to invoke" }, "params": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the tool to call" }, "arguments": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to search for." }, "context": { "type": "string", "description": "What the user is working on or trying to achieve. More specific context produces more relevant results." }, "author": { "type": "string", "description": "Restrict results to works by this author. Fuzzy matching: partial names, any casing, and minor trailing typos work, but the first few letters must be correct. The response's `author_filter.matched_authors` field shows which author names actually matched." }, "skill_used": { "type": "string", "description": "If this tool call is being made as part of executing a skill or prompt template, the name or identifier of that skill. Leave unset for direct, user-initiated questions." } }, "required": [ "question" ], "additionalProperties": false, "description": "Tool-specific arguments" } }, "required": [ "name", "arguments" ], "additionalProperties": false, "description": "Parameters for the tool call" }, "id": { "type": "number", "description": "Request identifier" } }, "required": [ "jsonrpc", "method", "params", "id" ], "additionalProperties": false, "example": { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "ask_oreilly_experts", "arguments": { "question": "What is a pytest fixture?" } }, "id": 3 } } } ], "produces": [ "application/json" ], "consumes": [ "application/json" ], "security": [ { "oauth2": [] } ] } }, "/api/expert/v1/mcp ": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "examples": { "application/json": { "jsonrpc": "2.0", "result": { "content": [ { "type": "text", "text": "{\"results\": {\"product_id\": \"9781098139575\", \"product_title\": \"Hypermodern Python Tooling\", \"authors\": \"Claudio Jolowicz\", \"offset\": 662, \"content\": \"Tests (and fixtures) can use a fixture by including a function parameter with\\nthe same name.\\nWhen pytest invokes the test function, it passes the return value\\nof the fixture function.\\nLet’s rewrite Example 6-4 to use the\\nfixture:\", \"citation_format\": \"[Hypermodern Python Tooling](https://learning.oreilly.com/library/view/-/9781098139575/ch06.html?orm_source=mcp) by Claudio Jolowicz\", \"citation_instruction\": \"ALWAYS cite this source using the clickable markdown link in 'citation_format' (e.g. \\\"According to [Title](url) by Author...\\\"). These links take users directly to the content on the O'Reilly platform.\", \"published_date\": \"2024-06-18\", \"child_title\": \"6. Testing with pytest\", \"url\": \"https://learning.oreilly.com/library/view/-/9781098139575/ch06.html?orm_source=mcp\", \"ourn\": \"urn:orm:book:9781098139575\", \"chapter_ourn\": \"urn:orm:book:9781098139575:chapter:ch06.html\"}}" } ], "isError": false }, "id": 4 } }, "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "result": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Content type, always `text` for this tool" }, "text": { "type": "string", "description": "JSON-encoded string. Parse it to get an object with a `results` key holding the full snippet — see the **Response** list under [`get_oreilly_citation`](#tag/Available-Tools/get_oreilly_citation) above for the fields." } }, "required": [ "type", "text" ] }, "description": "Array of content items returned by the tool" }, "isError": { "type": "boolean", "description": "Indicates if the result is an error" } }, "required": [ "content", "isError" ], "additionalProperties": false, "description": "The result of the tool call" }, "id": { "type": "number", "description": "Request identifier matching the request" } }, "required": [ "jsonrpc", "result", "id" ], "additionalProperties": false } }, "400": { "description": "Bad Request", "headers": {}, "examples": { "application/json": { "jsonrpc": "2.0", "error": { "code": -32602, "message": "Invalid params" }, "id": 1 } }, "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "error": { "type": "object", "properties": { "code": { "type": "number", "description": "JSON-RPC error code" }, "message": { "type": "string", "description": "Error message" }, "data": { "type": "object", "properties": {}, "description": "Additional error details" } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Error details" }, "id": { "type": "number", "description": "Request identifier matching the request" } }, "required": [ "jsonrpc", "error", "id" ], "additionalProperties": false } }, "401": { "description": "Unauthorized", "headers": {}, "examples": { "application/json": { "jsonrpc": "2.0", "error": { "code": -32602, "message": "Invalid params" }, "id": 1 } }, "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "error": { "type": "object", "properties": { "code": { "type": "number", "description": "JSON-RPC error code" }, "message": { "type": "string", "description": "Error message" }, "data": { "type": "object", "properties": {}, "description": "Additional error details" } }, "required": [ "code", "message" ], "additionalProperties": false, "description": "Error details" }, "id": { "type": "number", "description": "Request identifier matching the request" } }, "required": [ "jsonrpc", "error", "id" ], "additionalProperties": false } }, "403": { "description": "Forbidden", "headers": {}, "examples": { "application/json": { "error": "forbidden", "error_description": "The 'xmcp' (Expert MCP) permission is required." } }, "schema": { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "example": { "error": "forbidden", "error_description": "The 'xmcp' (Expert MCP) permission is required." } } } }, "summary": "Call Get Citation Tool", "operationId": "Call Get Citation Tool", "description": "Retrieve the full text of a snippet. The `product_id` and `offset` below are shown for illustration\nonly and will likely fail if used as-is — this tool only accepts pairs returned by a prior\n`ask_oreilly_experts` call, and results change as the library is updated. Always take\n`product_id` and `offset` from your own `ask_oreilly_experts` response.", "tags": [ "MCP Endpoint" ], "parameters": [ { "name": "Accept", "in": "header", "description": "e.g. application/json, text/event-stream", "required": false, "x-example": "application/json, text/event-stream", "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "description": "JSON-RPC version" }, "method": { "type": "string", "description": "MCP method to invoke" }, "params": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the tool to call" }, "arguments": { "type": "object", "properties": { "product_id": { "type": "string", "description": "The product ID from an `ask_oreilly_experts` result." }, "offset": { "type": "number", "description": "The snippet offset from an `ask_oreilly_experts` result, identifying the specific snippet within the product." }, "skill_used": { "type": "string", "description": "If this tool call is being made as part of executing a skill or prompt template, the name or identifier of that skill. Leave unset for direct, user-initiated calls." } }, "required": [ "product_id", "offset" ], "additionalProperties": false, "description": "Tool-specific arguments" } }, "required": [ "name", "arguments" ], "additionalProperties": false, "description": "Parameters for the tool call" }, "id": { "type": "number", "description": "Request identifier" } }, "required": [ "jsonrpc", "method", "params", "id" ], "additionalProperties": false, "example": { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "get_oreilly_citation", "arguments": { "product_id": "9781098139575", "offset": 662 } }, "id": 4 } } } ], "produces": [ "application/json" ], "consumes": [ "application/json" ], "security": [ { "oauth2": [] } ] } } }, "definitions": { "Initialize Session": {}, "Send Initialized Notification": {}, "List Available Tools": {}, "Call Content Search Tool": {}, "Call Ask Experts Tool": {}, "Call Get Citation Tool": {}, "Tool Arguments and Results": { "type": "object", "properties": {} }, "LanguageOptionsArray": { "type": "array", "items": { "type": "string", "enum": [ "en", "nl", "fr", "de", "it", "ja", "ko", "pl", "pt", "es", "ru", "zh" ] } }, "ContentTypesOptionsArray": { "type": "array", "items": { "type": "string", "enum": [ "articles", "books", "videos", "courses", "interactive", "certifications", "audiobooks", "playlists", "live" ] } }, "PublisherFilterArray": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "string", "example": "O'Reilly Media, Inc." } ] } }, "AuthorFilterArray": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "string", "example": "Claudio Jolowicz" } ] } }, "SearchArguments": { "type": "object", "properties": { "query": { "type": "string", "example": "Python machine learning", "description": "The query to perform a search for. Default: `*`. Maximum 500 characters." }, "n_items": { "type": "number", "example": 2, "description": "Number of items to return. Default: 5." }, "languages": { "$ref": "#/definitions/LanguageOptionsArray", "description": "Languages to filter by. Default: `[\"en\"]`" }, "content_types": { "$ref": "#/definitions/ContentTypesOptionsArray", "description": "Content types to filter by. Default: all content types." }, "publisher_filter": { "$ref": "#/definitions/PublisherFilterArray", "description": "Publishers to filter by. Default: none (all publishers)." }, "author_filter": { "$ref": "#/definitions/AuthorFilterArray", "description": "Authors to filter by. Default: none (all authors)." }, "order_by": { "type": "string", "enum": [ "relevance", "popularity", "rating", "date_added", "date_published", "last_updated", "upcoming_events" ], "description": "Field to order search results by. Omit this parameter unless user specifically requests ordering." }, "sort_order": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction. For dates, `desc` shows newer/upcoming content first, `asc` shows older content first. Default: `desc`." } } }, "AskExpertsArguments": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "example": "What is a pytest fixture?", "description": "The question to search for." }, "context": { "type": "string", "example": "I'm debugging a flaky test suite that relies on shared setup", "description": "What the user is working on or trying to achieve. More specific context produces more relevant results." }, "author": { "type": "string", "example": "Jolowicz", "description": "Restrict results to works by this author. Fuzzy matching: partial names, any casing, and minor trailing typos work, but the first few letters must be correct. The response's `author_filter.matched_authors` field shows which author names actually matched." }, "skill_used": { "type": "string", "example": "system-design-review", "description": "If this tool call is being made as part of executing a skill or prompt template, the name or identifier of that skill. Leave unset for direct, user-initiated questions." } } }, "CitationArguments": { "type": "object", "required": [ "product_id", "offset" ], "properties": { "product_id": { "type": "string", "example": "9781098139575", "description": "The product ID from an `ask_oreilly_experts` result." }, "offset": { "type": "number", "example": 662, "description": "The snippet offset from an `ask_oreilly_experts` result, identifying the specific snippet within the product." }, "skill_used": { "type": "string", "example": "system-design-review", "description": "If this tool call is being made as part of executing a skill or prompt template, the name or identifier of that skill. Leave unset for direct, user-initiated calls." } } }, "MCP Protocol Structures": { "type": "object", "properties": {} }, "MCPInitializeRequest": { "type": "object", "required": [ "jsonrpc", "method", "params", "id" ], "properties": { "jsonrpc": { "type": "string", "example": "2.0", "description": "JSON-RPC version" }, "method": { "type": "string", "example": "initialize", "description": "MCP method to invoke" }, "params": { "$ref": "#/definitions/InitializeParams", "description": "Initialization parameters" }, "id": { "type": "number", "description": "Request identifier" } } }, "InitializeParams": { "type": "object", "required": [ "protocolVersion", "capabilities", "clientInfo" ], "properties": { "protocolVersion": { "type": "string", "example": "2025-06-18", "description": "MCP protocol version" }, "capabilities": { "type": "object", "properties": {}, "description": "Client capabilities (can be empty object)" }, "clientInfo": { "$ref": "#/definitions/ClientInfo", "description": "Information about the client" } } }, "ClientInfo": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string", "example": "mcp", "description": "Client name" }, "version": { "type": "string", "example": "0.1.0", "description": "Client version" } } }, "MCPInitializeResponse": { "type": "object", "required": [ "jsonrpc", "result", "id" ], "properties": { "jsonrpc": { "type": "string", "example": "2.0", "description": "JSON-RPC version" }, "result": { "$ref": "#/definitions/InitializeResult", "description": "Initialization result" }, "id": { "type": "number", "description": "Request identifier matching the request" } } }, "InitializeResult": { "type": "object", "required": [ "protocolVersion", "capabilities", "serverInfo" ], "properties": { "protocolVersion": { "type": "string", "example": "2025-06-18", "description": "MCP protocol version supported by server" }, "capabilities": { "$ref": "#/definitions/ServerCapabilities", "description": "Server capabilities" }, "serverInfo": { "$ref": "#/definitions/ServerInfo", "description": "Information about the server" } } }, "ServerCapabilities": { "type": "object", "required": [ "tools" ], "properties": { "tools": { "$ref": "#/definitions/ToolsCapability", "description": "Tools-related capabilities" }, "experimental": { "type": "object", "properties": {}, "description": "Experimental capabilities" } } }, "ToolsCapability": { "type": "object", "required": [ "listChanged" ], "properties": { "listChanged": { "type": "boolean", "description": "Whether the tools list can change" } } }, "ServerInfo": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string", "example": "mcp-content-discovery-expert", "description": "Server name" }, "version": { "type": "string", "example": "1.15.0", "description": "Server version" } } }, "MCPInitializedNotification": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "example": "2.0", "description": "JSON-RPC version" }, "method": { "type": "string", "example": "notifications/initialized", "description": "Notification method (no id field since this is a notification, not a request)" } } }, "MCPListToolsRequest": { "type": "object", "required": [ "jsonrpc", "method", "id" ], "properties": { "jsonrpc": { "type": "string", "example": "2.0", "description": "JSON-RPC version" }, "method": { "type": "string", "example": "tools/list", "description": "MCP method to invoke" }, "id": { "type": "number", "example": 1, "description": "Request identifier" } } }, "MCPListToolsResponse": { "type": "object", "required": [ "jsonrpc", "result", "id" ], "properties": { "jsonrpc": { "type": "string", "example": "2.0", "description": "JSON-RPC version" }, "result": { "$ref": "#/definitions/ListToolsResult", "description": "List of available tools" }, "id": { "type": "number", "example": 1, "description": "Request identifier matching the request" } } }, "ListToolsResult": { "type": "object", "required": [ "tools" ], "properties": { "tools": { "$ref": "#/definitions/ToolDefinition", "description": "Array of available tools" } } }, "ToolDefinition": { "type": "array", "items": { "type": "object", "required": [ "name", "description", "inputSchema" ], "properties": { "name": { "type": "string", "example": "search_oreilly_content", "description": "Tool name" }, "description": { "type": "string", "example": "This tool performs a more traditional keyword search...", "description": "Tool description" }, "inputSchema": { "type": "object", "properties": {}, "description": "JSON Schema defining the tool's input parameters" } } } }, "SearchToolCallRequest": { "type": "object", "required": [ "jsonrpc", "method", "params", "id" ], "properties": { "jsonrpc": { "type": "string", "example": "2.0", "description": "JSON-RPC version" }, "method": { "type": "string", "example": "tools/call", "description": "MCP method to invoke" }, "params": { "$ref": "#/definitions/SearchToolCallParams", "description": "Parameters for the tool call" }, "id": { "type": "number", "example": 2, "description": "Request identifier" } } }, "SearchToolCallParams": { "type": "object", "required": [ "name", "arguments" ], "properties": { "name": { "type": "string", "example": "search_oreilly_content", "description": "The name of the tool to call" }, "arguments": { "$ref": "#/definitions/SearchArguments", "description": "Tool-specific arguments" } } }, "AskExpertsToolCallRequest": { "type": "object", "required": [ "jsonrpc", "method", "params", "id" ], "properties": { "jsonrpc": { "type": "string", "example": "2.0", "description": "JSON-RPC version" }, "method": { "type": "string", "example": "tools/call", "description": "MCP method to invoke" }, "params": { "$ref": "#/definitions/AskExpertsToolCallParams", "description": "Parameters for the tool call" }, "id": { "type": "number", "example": 3, "description": "Request identifier" } } }, "AskExpertsToolCallParams": { "type": "object", "required": [ "name", "arguments" ], "properties": { "name": { "type": "string", "example": "ask_oreilly_experts", "description": "The name of the tool to call" }, "arguments": { "$ref": "#/definitions/AskExpertsArguments", "description": "Tool-specific arguments" } } }, "CitationToolCallRequest": { "type": "object", "required": [ "jsonrpc", "method", "params", "id" ], "properties": { "jsonrpc": { "type": "string", "example": "2.0", "description": "JSON-RPC version" }, "method": { "type": "string", "example": "tools/call", "description": "MCP method to invoke" }, "params": { "$ref": "#/definitions/CitationToolCallParams", "description": "Parameters for the tool call" }, "id": { "type": "number", "example": 4, "description": "Request identifier" } } }, "CitationToolCallParams": { "type": "object", "required": [ "name", "arguments" ], "properties": { "name": { "type": "string", "example": "get_oreilly_citation", "description": "The name of the tool to call" }, "arguments": { "$ref": "#/definitions/CitationArguments", "description": "Tool-specific arguments" } } }, "SearchToolCallResponse": { "type": "object", "required": [ "jsonrpc", "result", "id" ], "properties": { "jsonrpc": { "type": "string", "example": "2.0", "description": "JSON-RPC version" }, "result": { "$ref": "#/definitions/SearchToolCallResult", "description": "The result of the tool call" }, "id": { "type": "number", "example": 2, "description": "Request identifier matching the request" } } }, "SearchToolCallResult": { "type": "object", "required": [ "content", "isError" ], "properties": { "content": { "$ref": "#/definitions/SearchTextContent", "description": "Array of content items returned by the tool" }, "isError": { "type": "boolean", "description": "Indicates if the result is an error" } } }, "SearchTextContent": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "example": "text", "description": "Content type, always `text` for this tool" }, "text": { "type": "string", "description": "JSON-encoded string. Parse it to get an object with a `search_results` key, whose values are content items keyed by ourn — see the **Search Results** metadata list under [`search_oreilly_content`](#tag/Available-Tools/search_oreilly_content) above for the per-item fields." } } } }, "AskExpertsToolCallResponse": { "type": "object", "required": [ "jsonrpc", "result", "id" ], "properties": { "jsonrpc": { "type": "string", "example": "2.0", "description": "JSON-RPC version" }, "result": { "$ref": "#/definitions/AskExpertsToolCallResult", "description": "The result of the tool call" }, "id": { "type": "number", "example": 3, "description": "Request identifier matching the request" } } }, "AskExpertsToolCallResult": { "type": "object", "required": [ "content", "isError" ], "properties": { "content": { "$ref": "#/definitions/AskExpertsTextContent", "description": "Array of content items returned by the tool" }, "isError": { "type": "boolean", "description": "Indicates if the result is an error" } } }, "AskExpertsTextContent": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "example": "text", "description": "Content type, always `text` for this tool" }, "text": { "type": "string", "description": "JSON-encoded string. Parse it to get an object with a `results` key containing `query`, a `citation_format` template, and a `results` array of matching snippets — see the **Response** list under [`ask_oreilly_experts`](#tag/Available-Tools/ask_oreilly_experts) above for the per-snippet fields." } } } }, "CitationToolCallResponse": { "type": "object", "required": [ "jsonrpc", "result", "id" ], "properties": { "jsonrpc": { "type": "string", "example": "2.0", "description": "JSON-RPC version" }, "result": { "$ref": "#/definitions/CitationToolCallResult", "description": "The result of the tool call" }, "id": { "type": "number", "example": 4, "description": "Request identifier matching the request" } } }, "CitationToolCallResult": { "type": "object", "required": [ "content", "isError" ], "properties": { "content": { "$ref": "#/definitions/CitationTextContent", "description": "Array of content items returned by the tool" }, "isError": { "type": "boolean", "description": "Indicates if the result is an error" } } }, "CitationTextContent": { "type": "array", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "example": "text", "description": "Content type, always `text` for this tool" }, "text": { "type": "string", "description": "JSON-encoded string. Parse it to get an object with a `results` key holding the full snippet — see the **Response** list under [`get_oreilly_citation`](#tag/Available-Tools/get_oreilly_citation) above for the fields." } } } }, "MCPErrorResponse": { "type": "object", "required": [ "jsonrpc", "error", "id" ], "properties": { "jsonrpc": { "type": "string", "example": "2.0", "description": "JSON-RPC version" }, "error": { "$ref": "#/definitions/ErrorObject", "description": "Error details" }, "id": { "type": "number", "example": 1, "description": "Request identifier matching the request" } } }, "ErrorObject": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "number", "example": -32602, "description": "JSON-RPC error code" }, "message": { "type": "string", "example": "Invalid params", "description": "Error message" }, "data": { "type": "object", "properties": {}, "description": "Additional error details" } } } }, "securityDefinitions": { "oauth2": { "type": "oauth2", "flow": "accessCode", "authorizationUrl": "", "tokenUrl": "", "scopes": {} } }, "tags": [ { "name": "Available Tools", "description": "This section documents the tools available through the MCP server.\n\n## search_oreilly_content\n\nThis tool performs a keyword search against for content on the O'Reilly learning platform and returns a list of matches with associated metadata.\nIt provides similar functionality and results as the `Search` feature available on the platform.\n\n**Use Cases:**\n\n- Keyword searches\n\n- Finding specific pieces of content\n\n- Searching for content from specific publishers or authors\n\n- Filtering by content type, language, or other attributes\n\n**Parameters:** (expand `params` → `arguments` in the request schema under **Call Content Search Tool** below for types, defaults, and allowed values)\n\n- `query`\n\n- `n_items`\n\n- `languages`\n\n- `content_types`\n\n- `publisher_filter`\n\n- `author_filter`\n\n- `order_by`\n\n- `sort_order`\n\n**Search Results:**\n\nThe actual search results are returned as text which when converted to `json` comes in a format like\n\n```json\n{\n \"search_results\": {\n \"urn:orm:book:9781617296901\": {...},\n \"urn:orm:book:9781098118792\": {...}\n }\n}\n```\n\nEach piece of content returned also includes the following metadata:\n\n- ourn: `urn:orm:book:9781491954348` (string, required) - O'Reilly URN identifier\n\n- title: `Python for Data Analysis` (string, required) - Content title\n\n- authors (array[string], required) - List of author names\n - `Wes McKinney`\n\n- publisher_names (array[string], required) - List of publisher names\n - `O'Reilly Media, Inc.`\n\n- display_format: `book` (string, required) - Display format of the content (e.g., book, video, audiobook, live-event-series, article, scenario, etc.)\n\n- marketing_type: `book` (string, required) - Marketing type classification\n\n- url: `https://learning.oreilly.com/library/view/-/9781491954348/` (string, required) - URL to access the content on the O'Reilly platform\n\n- image_url: `https://learning.oreilly.com/covers/9781491954348/` (string, required) - URL to cover/thumbnail image\n\n- page_count: 550 (number, optional) - Number of pages (for books/articles, null for other types)\n\n- duration: 3600 (number, optional) - Duration in seconds (for videos/audiobooks, null for other types)\n\n- tags (array[string], required) - Associated tags/categories. May be empty.\n\n- relevance_score: 0.84 (number, optional) - How well the result matches `query`, 0.0-1.0. Less meaningful for the default wildcard query.\n\n- publication_date: `2025-02-23` (string, required) - Date of publication for the content. For `live-events` this represents when it was first introduced\n\n- live_event_start_dates: (array[string], optional) - Dates on which an event is being held. Multiple dates represents multiple sessions in an event that has consecutive sessions\n - `2025-11-11`\n\n**Notes:**\n\n- The `query` search is not required and by default is a wildcard search\n - Providing other filters and no `query` allows finding a general list of content according to those filters\n\n- When searching by author or publisher, use of the filter parameters tends to provide better results\n\n- By default, 5 results will be returned\n\n- English is the default language for results\n\n- Searches for live-events will never return events with no upcoming registrations\n\n- For `order_by` parameter:\n - The default `None` uses a weighted mix to order content\n - `relevance`: sorts by relevance metric\n - `rating`: sort by average rating\n - `popularity`: sorts by content popularity\n - `date_published`: when content was released publicly\n - `date_added`: when content was added to the platform\n - `last_updated`: only valid for collections/playlists\n - `upcoming_events`: only valid for live-events, returns the soonest events top\n\n## ask_oreilly_experts\n\nThis tool searches O'Reilly's expert-authored learning library — books, video courses, and other\nresources written by named industry experts — for grounded, citable guidance on programming,\nsoftware engineering, and technology decisions. It's built for answering a specific technical\nquestion, not for browsing: use `search_oreilly_content` instead when the goal is to discover\ntitles, filter by publisher or format, or find live events.\n\n**Use Cases:**\n\n- System design and architecture advice\n\n- Weighing the pros and cons of competing technical approaches\n\n- Chapter-level recommendations for a specific technical question\n\n- Grounding an answer in vetted, citable source material\n\n**Parameters:** (expand `params` → `arguments` in the request schema under **Call Ask Experts Tool** below for types and defaults)\n\n- `question` (required) - The question to search for.\n\n- `context` (optional) - What the user is working on or trying to achieve. More specific context produces more relevant results.\n\n- `author` (optional) - Restrict results to a specific author. Matching is fuzzy — partial names, any casing, and minor trailing typos work (`kleppmann` matches `Martin Kleppmann`), but the first few letters must be correct. The response's `author_filter.matched_authors` field shows which author names actually matched.\n\n- `skill_used` (optional) - Identifier of the skill or prompt template making this call, if applicable. Leave unset for direct, user-initiated questions.\n\n**Response:**\n\nReturns a top-level `results` object containing the `query` that was searched, a `citation_format`\ntemplate, and a `results` array of matching snippets. Each snippet includes: (see the response\nsample under **Call Ask Experts Tool** below for a full example)\n\n- `product_id`, `product_title` - Identifiers for the source product.\n\n- `authors` - A single comma-separated string, not an array.\n\n- `published_date`, `child_title` (optional) - Publication date and the chapter/section containing the snippet.\n\n- `offset` - Identifies the specific snippet within the product.\n\n- `url` - Link to the content, suitable for citation.\n\n- `snippet_preview` - A short preview, typically up to ~300 characters but often shorter.\n\n- `relevance_score` - 0.0-1.0 relevance score returned with the result.\n\n- `ourn`/`chapter_ourn` - O'Reilly URN identifiers for the product and chapter.\n\nResults contain short previews only, not full snippet text. Call `get_oreilly_citation` with a\nresult's `product_id` and `offset` to retrieve the full content of that snippet.\n\n## get_oreilly_citation\n\nThis tool retrieves the full, citable text of a snippet identified by a prior `ask_oreilly_experts`\ncall. It only works with `product_id`/`offset` pairs returned by `ask_oreilly_experts` — it cannot\nbe used to look up arbitrary content.\n\n**Parameters:** (expand `params` → `arguments` in the request schema under **Call Get Citation Tool** below for types)\n\n- `product_id` (required) - The product ID from an `ask_oreilly_experts` result.\n\n- `offset` (required) - The snippet offset from an `ask_oreilly_experts` result, identifying the specific snippet within the product.\n\n- `skill_used` (optional) - Identifier of the skill or prompt template making this call, if applicable.\n\n**Response:** (see the response sample under **Call Get Citation Tool** below for a full example)\n\n- `product_id`, `product_title` - Identifiers for the source product.\n\n- `authors` - A single comma-separated string, not an array.\n\n- `offset` - Echoed back from the request.\n\n- `content` - The full snippet text.\n\n- `url` - Link to the content, suitable for citation.\n\n- `citation_format` - A pre-formatted citation string.\n\n- `citation_instruction` - Guidance for how to present the citation.\n\n- `ourn`/`chapter_ourn` - O'Reilly URN identifiers for the product and chapter.\n\n- `child_title`, `published_date` (optional)" }, { "name": "MCP Endpoint", "description": "## MCP Streamable HTTP Transport\n\nThis server implements the Model Context Protocol (MCP) using Streamable HTTP. All tool calls are made through this single endpoint using the MCP protocol format.\nFor most purposes using one of the available MCP SDKs or a preexisting client will fit most needs but custom clients can be implemented using according\nto the requests below.\n\nMore information on the Streamable HTTP transport can be found in the [MCP Specification Documents](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http)\n\n**Required Headers:**\n\n- `Authorization: Bearer {YOUR_TOKEN}` - Authentication token\n\n- `Accept: application/json, text/event-stream` - Accepted response formats (this server only returns `application/json`)\n\nEvery request below assumes the caller is authenticated **and** entitled to Expert MCP. If the\naccount isn't entitled, every one of these requests — including `initialize` — instead returns an\nHTTP `403` with the body shown in [Access & Entitlement](#section/Access-and-Entitlement).\n\nThe typical flow is:\n1. **Initialize** - Establish the session and negotiate capabilities\n2. **List Tools** - Discover available tools\n3. **Call Tool** - Execute a specific tool" } ] }