MCP Server library with search, fetch, and do primitives - the core package for building MCP servers
npm install @dotdo/mcpMCP Server library with search, fetch, and do primitives - the core package for building MCP (Model Context Protocol) servers.
``bash`
npm install @dotdo/mcpor
pnpm add @dotdo/mcp
`typescript
import { createMCPServer, createScope } from '@dotdo/mcp'
import { Hono } from 'hono'
// Define your domain bindings for the sandboxed do tool
const scope = createScope({
bindings: {
db: {
query: async (sql: string) => {
// Your database query implementation
return []
}
},
api: {
fetch: async (url: string) => {
// Your API fetch implementation
return {}
}
}
},
permissions: {
allowNetwork: false // Disable raw fetch in sandbox
},
timeout: 5000
})
// Create the MCP server
const mcp = createMCPServer({
search: async (query, options) => {
// Implement search logic
return [{ id: '1', title: 'Result', content: 'Content...' }]
},
fetch: async (id, options) => {
// Implement fetch logic
return { id, content: 'Fetched content' }
},
do: scope
})
// Mount on Hono
const app = new Hono()
app.post('/mcp', mcp.getHttpHandler())
`
The MCP server exposes three core tools:
Search for information in your knowledge base.
`typescript`
{
query: string // The search query
limit?: number // Maximum results (optional)
offset?: number // Skip results (optional)
}
Fetch a specific resource by identifier.
`typescript`
{
id: string // Resource identifier
includeMetadata?: boolean // Include metadata (optional)
format?: string // Desired format (optional)
}
Execute TypeScript code in a sandboxed environment with your domain bindings.
`typescript`
{
code: string // TypeScript code to execute
}
The library includes built-in authentication support:
`typescript
import { createMCPServer, createAuthMiddleware } from '@dotdo/mcp'
const mcp = createMCPServer({
// ... tools config
auth: {
mode: 'anon+auth', // 'anon' | 'anon+auth' | 'auth-required'
oauth: {
introspectionUrl: 'https://auth.example.com/introspect'
},
apiKey: {
verifyUrl: 'https://keys.example.com/verify'
}
}
})
// Use with Hono middleware
const app = new Hono()
const authMiddleware = createAuthMiddleware(mcp.getAuthConfig())
app.use('/mcp/*', authMiddleware)
app.post('/mcp', mcp.getHttpHandler())
`
- anon - Anonymous access only (readonly)anon+auth
- - Both anonymous and authenticated accessauth-required
- - Authentication required for all access
The library auto-detects token types:
- JWT tokens (three dot-separated parts)
- API keys with sk_ prefixdo_
- API keys with prefix
`typescript
// Main entry
import { createMCPServer } from '@dotdo/mcp'
// Server for Node.js (uses vm2)
import { createMCPServerNode } from '@dotdo/mcp/node'
// Tools
import { createSearchTool, createFetchTool, createDoTool } from '@dotdo/mcp/tools'
// Scope creation
import { createScope, validateScope } from '@dotdo/mcp/scope'
// Authentication
import {
createAuthMiddleware,
authenticate,
ANONYMOUS_CONTEXT
} from '@dotdo/mcp/auth'
`
For Cloudflare Workers with sandboxed code execution:
`typescript
import { createMCPServer } from '@dotdo/mcp'
export default {
async fetch(request: Request, env: Env): Promise
const mcp = createMCPServer(config, { env })
return mcp.getHttpHandler()(request)
}
}
`
For Node.js environments:
`typescript
import { createMCPServerNode } from '@dotdo/mcp/node'
const mcp = createMCPServerNode(config)
`
This package optionally integrates with @dotdo/types for shared type definitions. Install it as a peer dependency if you want to use types from the broader @dotdo ecosystem:
`bash``
pnpm add @dotdo/types
MIT