feat: add new tool to load mcp resources (#137)

**Context**
As part of our onboarding devx, we want to add a set of steps and
instructions to help users integrate their existing projects with Neon.
We added [this get started
guide](https://github.com/neondatabase-labs/ai-rules/blob/main/neon-get-started.mdc).
This will typically be run through an `init` command that sets up the
MCP server for the user.

**What changes are proposed in this pull request?**
This PR adds a `load_resource` tool to expose guides (starting with our
`Get Started` resource) to the agent via a MCP tool. This is useful for
two reasons.
1. Some IDEs don't support MCP resources and only have access to MCP
tools
2. MCP resources are typically less likely to be loaded into context by
agents (unless we explicitly instruct the agent to use the MCP resource)

**How was this tested?**
Tested this by deploying to preview env
<img width="396" height="913" alt="Screenshot 2025-11-11 at 19 33 03"
src="https://github.com/user-attachments/assets/919bdc93-9fa2-4f73-adc9-cfa74257cd1d"
/>

#[LKB-6294](https://databricks.atlassian.net/browse/LKB-6294)

Author: rodneyshibu

src/resources.ts

@@ -1,12 +1,16 @@
 import { ReadResourceCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Resource } from '@modelcontextprotocol/sdk/types.js';
 
-async function fetchRawGithubContent(rawPath: string) {
+export async function fetchRawGithubContent(rawPath: string) {
   const path = rawPath.replace('/blob', '');
 
-  return fetch(`https://raw.githubusercontent.com${path}`).then((res) =>
-    res.text(),
-  );
+  const response = await fetch(`https://raw.githubusercontent.com${path}`);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch GitHub content: ${response.status} ${response.statusText}`,
+    );
+  }
+  return response.text();
 }
 
 export const NEON_RESOURCES = [

src/tools/definitions.ts

@@ -26,6 +26,7 @@ import {
   compareDatabaseSchemaInputSchema,
   searchInputSchema,
   fetchInputSchema,
+  loadResourceInputSchema,
 } from './toolsSchema.js';
 
 export const NEON_TOOLS = [
@@ -916,4 +917,27 @@ export const NEON_TOOLS = [
     inputSchema: fetchInputSchema,
     readOnlySafe: true,
   },
+  {
+    name: 'load_resource' as const,
+    description: `
+  <use_case>
+    Loads comprehensive Neon documentation and usage guidelines from GitHub. This tool provides instructions for various Neon features and workflows.
+    
+    Use this tool when:
+    - User says "Get started with Neon" or similar onboarding phrases (with neon-get-started subject)
+    - User needs detailed guidance for initial Neon setup and configuration (with neon-get-started subject)
+    - You need comprehensive context about Neon workflows and best practices (with neon-get-started subject)
+    
+    Available subjects:
+    - neon-get-started: Comprehensive interactive guide covering organization/project setup, database configuration, connection strings, dependency installation, schema creation/migration, etc.
+  </use_case>
+
+  <important_notes>
+    - This tool provides general guidance on different subjects relevant to Neon.
+    - This tool returns the FULL documentation content
+    - Load this resource early when users need onboarding guidance
+  </important_notes>`,
+    inputSchema: loadResourceInputSchema,
+    readOnlySafe: true,
+  },
 ];

src/tools/tools.ts

@@ -15,6 +15,7 @@ import { handleProvisionNeonAuth } from './handlers/neon-auth.js';
 import { handleSearch } from './handlers/search.js';
 import { handleFetch } from './handlers/fetch.js';
 import { getMigrationFromMemory, persistMigrationToMemory } from './state.js';
+import { fetchRawGithubContent, NEON_RESOURCES } from '../resources.js';
 
 import {
   getDefaultDatabase,
@@ -1014,6 +1015,26 @@ async function handleListSharedProjects(
   return response.data.projects;
 }
 
+async function handleLoadResource({ subject }: { subject: string }) {
+  const resource = NEON_RESOURCES.find((r) => r.name === subject);
+  if (!resource) {
+    throw new InvalidArgumentError(`Resource not found: ${subject}`);
+  }
+
+  try {
+    const url = new URL(resource.uri);
+    const path = url.pathname;
+    const content = await fetchRawGithubContent(path);
+    return content;
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error ? error.message : 'Unknown error';
+    throw new Error(
+      `Failed to load resource "${resource.name}": ${errorMessage}`,
+    );
+  }
+}
+
 async function handleCompareDatabaseSchema(
   params: GetProjectBranchSchemaComparisonParams,
   neonClient: Api<unknown>,
@@ -1596,4 +1617,16 @@ export const NEON_HANDLERS = {
   fetch: async ({ params }, neonClient, extra) => {
     return await handleFetch(params, neonClient, extra);
   },
+
+  load_resource: async ({ params }) => {
+    const content = await handleLoadResource({ subject: params.subject });
+    return {
+      content: [
+        {
+          type: 'text',
+          text: content,
+        },
+      ],
+    };
+  },
 } satisfies ToolHandlers;

src/tools/toolsSchema.ts

@@ -358,3 +358,11 @@ export const fetchInputSchema = z.object({
       'The ID returned by the search tool to fetch detailed information about the entity',
     ),
 });
+
+export const loadResourceInputSchema = z.object({
+  subject: z
+    .enum(['neon-get-started'])
+    .describe(
+      'The subject of the resource to load. Options: neon-get-started (Neon getting started guide).',
+    ),
+});