Model Context Protocol (MCP) Documentation

{
  "mcpServers": {
    "janisheckcom": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.janisheck.com/mcp"
      ]
    }
  }
}

Overview

This site offers enhanced direct integration capabilities for AI assistants through two primary endpoints: NLWeb (`/ask`) for natural language queries and MCP (`/mcp`) for structured JSON-RPC interactions, including NLWeb passthrough and specific MCP tool/resource methods.

These new endpoints, powered by Netlify Functions, provide a more robust and flexible way for AI to access and interact with site content compared to previous implementations.

Available Endpoints

• /ask (NLWeb)

  Primary endpoint for natural language queries. Supports standard JSON requests and Server-Sent Events (SSE) for streaming responses. Ideal for conversational AI.

• /mcp (NLWeb + MCP)

  A versatile JSON-RPC 2.0 endpoint. It can act as a passthrough for NLWeb queries (always non-streaming JSON) and also supports standard Model Context Protocol (MCP) methods for tools and resources. Recommended for MCP clients like Claude.

Note: Older endpoints like /api/mcp, /api/mcp-debug, and /api/mcp-static are now deprecated and may be removed in the future. Please migrate to the new endpoints.

NLWeb Functionality (via /ask or /mcp)

NLWeb (Natural Language Web) provides a conversational interface to web content. It's designed to be stateless, processing each query independently.

NLWeb Request Parameters:

When querying NLWeb (either directly to /ask or wrapped in an MCP request to /mcp), the following parameters can be used in the JSON request body:

• query (string, required): The natural language query.
• site (string, optional): Token for data subset (currently defaults, not strictly enforced).
• prev (string, optional): Comma-separated list of previous query IDs or contextual snippets.
• decontextualized_query (string, optional): A version of the query with context already resolved.
• streaming (boolean or string, optional): Controls streaming behavior for /ask. Defaults to true if not provided. Interpreted as false if the value is false (boolean), "0" (string), or "false" (string, case-insensitive). Otherwise, interpreted as true. When NLWeb is called via /mcp, this parameter influences the streaming attribute in the NLWeb JSON response, but the /mcp endpoint itself always returns a single, non-streaming JSON-RPC response.
• query_id (string, optional): Client-provided ID for the query. Auto-generated if missing.
• mode (string, optional): Specifies the processing mode.
  • list (default): Returns a list of relevant content items.
  • summarize: (Currently stubbed) Intended to summarize content.
  • generate: (Currently stubbed) Intended to generate content based on the query.

NLWeb JSON Response Structure:

A successful NLWeb JSON response (from /ask non-streaming, or as the result in an /mcp response) will typically have the following structure:

{
  "query_id": "string",
  "attributes": {
    "site": "string",
    "mode": "string",
    "streaming": boolean,
    "received_prev_count": number,
    "has_decontextualized_query": boolean
  },
  "results": [
    {
      "url": "string",
      "name": "string",
      "site": "string",
      "score": number,
      "description": "string",
      "schema_object": { /* frontmatter and content */ }
    },
    // ... more results
  ]
}

For /ask with streaming, responses are sent as Server-Sent Events (SSE), where each event's `data` field contains a JSON object similar to the above.

MCP Functionality on /mcp Endpoint

The /mcp endpoint is a JSON-RPC 2.0 compliant server. Besides wrapping NLWeb queries, it also supports standard MCP methods for discovering and interacting with tools and resources.

Supported MCP Methods:

• tools/list (alias: list_tools):

  Lists available tools. Currently includes "searchBlog".

• tools/call (alias: call_tool):

  Calls a specific tool. For "searchBlog", params are { name: 'searchBlog', args: { query: 'your search term' } }.

• resources/list (alias: list_prompts):

  Lists all available blog posts on janisheck.com. Each post is returned as a resource object that can be used as a prompt or for direct reading.

• resources/read (alias: get_prompt):

  Reads a specific resource. Params are { uri: 'blog://slug-of-post' }.

All requests to and responses from these MCP methods use the standard JSON-RPC 2.0 object structure ({ jsonrpc: '2.0', method: '...', params: {...}, id: '...' } for requests).

Accessing Blog Post Content

All blog post content on janisheck.com is accessible to AI assistants through the new endpoints. Here's how:

• Direct Natural Language Queries to /ask:

  Use the /ask endpoint (or nlweb/handleNLWebRequest method via /mcp) with a query. The system uses the getBlogPosts function, which searches titles, descriptions, and full content. If no query is provided, it now returns all blog posts.

• Searching with tools/call and searchBlog via /mcp:

  Use the searchBlog tool through the tools/call MCP method. Provide a query in the arguments (e.g., { args: { query: 'your search term' } }) to find relevant posts.

• Listing All Posts with resources/list via /mcp:

  Use the resources/list MCP method (optionally with params: { type: 'blog' }). This will return a complete list of all blog posts, each with its URI (e.g., blog://slug-of-post).

• Reading Specific Posts with resources/read via /mcp:

  Once you have a post's URI (e.g., from resources/list or a search result), use the resources/read MCP method with the URI (e.g., { uri: 'blog://slug-of-post' }) to fetch its full frontmatter and content.

These methods ensure comprehensive access to all blog articles, allowing AI assistants to effectively use the site's knowledge base.

How to Connect AI Assistants

To connect Claude or another MCP-compatible AI assistant:

1. In your AI assistant's settings for MCP servers (e.g., Claude Desktop: Settings > Remote MCP Servers).
2. Add a new server with the URL:

   https://www.janisheck.com/mcp

3. Name the server (e.g., "JanisheckCom_NLWeb_MCP").
4. Save and enable the integration in your conversation.

Example Prompts (for MCP Clients like Claude via /mcp)

When using an MCP client connected to the /mcp endpoint, you can leverage the searchBlog tool:

• "Search for blog posts about AI on janisheck.com"
• "Find articles related to Next.js on Joey's site using searchBlog"
• "What has Joey written about Python?"

If the AI is capable of more general NLWeb queries (and the MCP client passes them through, or if you are querying /ask directly), you might also try:

• "Show me all posts on janisheck.com." (as getBlogPosts now returns all if no query)
• "Summarize the post 'my-post-slug' from janisheck.com." (Note: summarize mode is currently stubbed but the content can be retrieved for summarization by the AI itself.)

Technical Details

The new NLWeb and MCP integration is built using:

• Netlify Functions:
  • netlify/functions/nlweb.js: Core NLWeb logic.
  • netlify/functions/ask.js: Handles /ask endpoint (JSON & SSE).
  • netlify/functions/nlweb-mcp.js: Handles /mcp endpoint (JSON-RPC for NLWeb & MCP methods).
• Custom lightweight implementations for NLWeb and MCP handling. The /mcp endpoint directly parses and responds to JSON-RPC 2.0 requests for its supported MCP methods and for NLWeb passthrough. It does not use the @modelcontextprotocol/sdk or the StreamableHTTPServerTransport class for serving these requests, differing from some other MCP server examples.

The primary endpoints are:

• /ask
• /mcp

Legacy endpoints like /api/mcp are deprecated.

Testing Tools

If you want to test the MCP endpoints without connecting an AI assistant, you can use our MCP Testing Interface.