Planning MCP server implementation with Ask tool

let's plan on implementing an MCP server for this. some ideas:

- Cursor needs to be able to ask questions: explaining its usecase and its question. The answer should be grounded by the extensive code samples from the actual source code
- Have a more raw search to kinda like list/grep/cat files from the library, as second potential working mode

i imagine an Ask tool? thea idea of providing a more raw search is brilliant, also. forums.basehub.com/owner/repo/bash and POST it any bash command? haha.

a challenge would be authentication and billing: how can we charge for those request without it being a pain for users? i guess with mcp auth? and maybe the bash endpoint is free of charge

This is a great idea! Let me explore the codebase to understand the current architecture and then we can plan the MCP server implementation.

No MCP yet. Let me check how billing works with Autumn and look at the existing API patterns:

Let me check how the app currently handles requests and the LLM endpoint:

Now let me understand the current flow better and think about MCP:

Now let me check the mcp-handler and vercel mcp adapter for Next.js:

Now I have a good picture. Let me draft a plan for the MCP server implementation:

##MCP Server Implementation Plan for Forums

###Overview

We'll expose an MCP server at forums.basehub.com/mcp (or similar) with two main tool categories:

1. Ask - AI-grounded answers with source code (paid, via Autumn billing)
2. Explore - Raw filesystem exploration tools (free or low-cost)

###Architecture

app/
  mcp/
    [...transport]/
      route.ts       # MCP handler entry point
lib/
  mcp/
    tools/
      ask.ts         # AI-grounded Q&A tool
      explore.ts     # List, Grep, Read (reuse existing agent/tools)
    auth.ts          # OAuth 2.1 + Autumn billing integration

###Tools

####1. Ask Tool (Paid)

{
  name: "ask",
  description: "Ask a question about a GitHub repository. Returns AI-grounded answers with source code snippets.",
  inputSchema: {
    owner: z.string(),      // e.g., "vercel"
    repo: z.string(),       // e.g., "ai"
    question: z.string(),   // The actual question
    context?: z.string(),   // Optional: what you're trying to build
  }
}

Under the hood:

• Spins up/reuses a Vercel Sandbox (your existing workspace.ts logic)
• Runs the same responseAgent flow but returns structured response instead of streaming to DB
• Charges credits via Autumn

####2. Explore Tools (Free or very cheap)

Reuse your existing agent/tools/index.ts:

• list - List directory contents
• grep - Search patterns in files
• read - Read file contents
• bash - Execute arbitrary bash commands (sandboxed)

The bash idea is wild but genius for power users! Could be rate-limited per IP/user.

###Authentication & Billing

Option A: OAuth 2.1 (Full MCP spec compliance)

// User authorizes via GitHub OAuth (existing better-auth flow)
// MCP client receives access token
// Token validated on each request
// Autumn checks/deducts credits

Option B: API Keys (Simpler)

// User generates API key in dashboard
// Key passed in MCP config
// Key → userId → Autumn billing

Recommend starting with Option B for MVP - much simpler:

// Cursor MCP config
{
  "forums": {
    "url": "https://forums.basehub.com/mcp",
    "headers": {
      "Authorization": "Bearer <api_key>"
    }
  }
}

###Billing Tiers

The free tools bring users in, ask converts them to paying.

###Implementation Steps

1. Add mcp-handler dependency
2. Create route at app/mcp/[...transport]/route.ts
3. Extract tool logic from agent/tools/index.ts to be reusable
4. Create ask tool that wraps responseAgent (non-streaming mode)
5. Add API key generation to user dashboard
6. Wire up Autumn billing for ask calls

###Example Usage (Cursor)

User: "How does basehub-ai/forums handle post creation?"

[MCP calls `ask` with owner="basehub-ai", repo="forums", question="How does post creation work?"]

Response: 
Based on the source code:

Posts are created via server action in `lib/actions/posts.ts`:
```typescript
export async function createPost({ ... }) {
  // validates input with zod
  // inserts into posts table
  // triggers category-agent for auto-categorization
  // revalidates cache
}

The form is in components/composer.tsx which calls this action...

### Questions to Resolve

1. **Should `ask` stream or return complete?** MCP supports streaming, could do either
2. **Rate limits for free tools?** Suggest 100/hour for authenticated, 10/hour for anon
3. **Bash scope?** Only within cloned repo directory, with timeout
4. **Separate endpoints?** `forums.basehub.com/mcp` vs `forums.basehub.com/{owner}/{repo}/mcp` per-repo

---

Want me to start implementing any part of this? The `mcp-handler` integration is pretty straightforward, and we can reuse a lot of your existing agent code.

thoughts on building it with xmcp? https://forums.basehub.com/basementstudio/xmcp/2

and also doing oauth instead of api key auth?

Explore seems too ambiguous. AskForum, BashForum? we impl a bash tool and just receive a bash command

Now let me look at the xmcp repo directly to understand OAuth support and the architecture better:

This is great - xmcp has excellent OAuth support via @xmcp-dev/better-auth and file-system based tool routing. Let me refine the plan:

##Revised MCP Server Plan with xmcp + OAuth

###Why xmcp is perfect here:

1. File-system routing - tools in src/tools/ auto-register
2. Better Auth integration - @xmcp-dev/better-auth plugin with OIDC provider
3. Already using better-auth - your existing lib/auth.ts can be reused
4. Middleware support - billing checks via Autumn

###Tools (renamed)

The BashForum approach is cleaner - users can do ls, grep, cat, find, whatever they need. One tool, infinite flexibility.

###Project Structure

src/
  tools/
    ask-forum.ts       # AskForum tool
    bash-forum.ts      # BashForum tool
  middleware.ts        # Better Auth + Autumn billing
xmcp.config.ts

###src/tools/ask-forum.ts

import { z } from "zod"
import type { ToolMetadata } from "xmcp"
import { getBetterAuthSession } from "@xmcp-dev/better-auth"
import { autumn } from "@/lib/autumn"
import { responseAgent } from "@/agent/response-agent"

export const schema = {
  owner: z.string().describe("GitHub repo owner"),
  repo: z.string().describe("GitHub repo name"),
  question: z.string().describe("Your question about the codebase"),
  context: z.string().optional().describe("What you're building/debugging"),
}

export const metadata: ToolMetadata = {
  name: "ask-forum",
  description: "Ask a question about a GitHub repository. Returns AI-grounded answers with actual source code.",
}

export default async function askForum({ owner, repo, question, context }) {
  const session = await getBetterAuthSession()
  
  // Check/deduct credits via Autumn
  const check = await autumn.check({ customer_id: session.userId, feature_id: "ask_credits" })
  if (!check.data?.allowed) {
    return { content: [{ type: "text", text: "Insufficient credits. Visit forums.basehub.com to upgrade." }] }
  }
  
  // Run the existing agent logic (extract to reusable fn)
  const answer = await generateAnswer({ owner, repo, question, context, userId: session.userId })
  
  await autumn.track({ customer_id: session.userId, feature_id: "ask_credits", delta: -1 })
  
  return { content: [{ type: "text", text: answer }] }
}

###src/tools/bash-forum.ts

import { z } from "zod"
import type { ToolMetadata } from "xmcp"
import { getWorkspace } from "@/agent/workspace"

export const schema = {
  owner: z.string().describe("GitHub repo owner"),
  repo: z.string().describe("GitHub repo name"),
  command: z.string().describe("Bash command to execute (e.g., 'ls -la src/', 'grep -r useState', 'cat package.json')"),
}

export const metadata: ToolMetadata = {
  name: "bash-forum",
  description: "Execute a bash command in a cloned GitHub repository. Use for exploring codebases: ls, grep, cat, find, head, tail, wc, etc.",
}

export default async function bashForum({ owner, repo, command }) {
  // Rate limit check (no auth required, but IP-limited)
  
  const workspace = await getWorkspace({ owner, repo })
  
  const result = await workspace.sandbox.runCommand("bash", ["-c", `
    cd ${workspace.path}
    timeout 30 ${command}
  `])
  
  return {
    content: [{
      type: "text",
      text: result.stdout || result.stderr || "(no output)"
    }]
  }
}

###src/middleware.ts (OAuth + Billing)

import { betterAuthProvider } from "@xmcp-dev/better-auth"
import { db } from "@/lib/db/client"

export default betterAuthProvider({
  database: db, // reuse existing drizzle connection
  baseURL: process.env.NEXT_PUBLIC_URL || "https://forums.basehub.com",
  secret: process.env.BETTER_AUTH_SECRET,
  providers: {
    // Use your existing GitHub OAuth!
    github: {
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET,
    }
  }
})

###xmcp.config.ts

import { XmcpConfig } from "xmcp"

const config: XmcpConfig = {
  http: true,
  experimental: {
    adapter: "nextjs",
  },
  paths: {
    tools: "src/tools",
    prompts: false,
    resources: false,
  },
}

export default config

###OAuth Flow (User Experience)

1. User adds to Cursor:

   {
     "forums": {
       "url": "https://forums.basehub.com/mcp"
     }
   }
   

2. First tool call → Cursor opens browser → GitHub OAuth → user logs in

3. Token stored in Cursor, subsequent calls authenticated

4. AskForum checks Autumn credits, BashForum is free

###Questions

1. BashForum auth? Could be:

   • Fully anonymous (IP rate-limited only)
   • Optional auth (higher limits if logged in)
   • Required auth (simplest billing story)

2. Sandbox sharing? BashForum and AskForum could share the same sandbox for a user+repo combo (your existing redis-backed sandbox pooling)

3. Output format for AskForum?

   • Raw markdown (let Claude/GPT format)
   • Structured JSON with code blocks
   • Stream chunks?

Want me to start implementing? I'd suggest starting with BashForum since it's simpler and reuses your existing sandbox code directly.