docs: Add TypeScript SDK reference documentation #618
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
TheMostlyGreat
force-pushed
the
docs/typescript-sdk-reference
branch
2 times, most recently
from
a0d1ead to
8084dcc
Compare
TheMostlyGreat
force-pushed
the
docs/typescript-sdk-reference
branch
3 times, most recently
from
069d929 to
fa8860d
Compare
TheMostlyGreat
force-pushed
the
docs/typescript-sdk-reference
branch
2 times, most recently
from
7ccf8c5 to
0dac123
Compare
TheMostlyGreat
force-pushed
the
docs/typescript-sdk-reference
branch
from
1bc4117 to
1d78c3a
Compare
TheMostlyGreat
force-pushed
the
docs/typescript-sdk-reference
branch
from
a49ad13 to
1764c47
Compare
TheMostlyGreat
force-pushed
the
docs/typescript-sdk-reference
branch
from
b470efb to
2cf571a
Compare
TheMostlyGreat
force-pushed
the
docs/typescript-sdk-reference
branch
from
5dd48bf to
841a5cf
Compare
TheMostlyGreat
force-pushed
the
docs/typescript-sdk-reference
branch
from
2399a45 to
272a40a
Compare
TheMostlyGreat
force-pushed
the
docs/typescript-sdk-reference
branch
from
d8f1169 to
8253a7a
Compare
TheMostlyGreat
force-pushed
the
docs/typescript-sdk-reference
branch
from
77fac2f to
4a4f722
Compare
TheMostlyGreat
force-pushed
the
docs/typescript-sdk-reference
branch
from
b92a1d3 to
ea77ca4
Compare
## Summary
Complete reference documentation for the TypeScript MCP Server SDK (arcade-mcp),
providing feature parity with the Python SDK while using TypeScript-idiomatic patterns.
## New Files
- `typescript/overview/` - MCPApp API, tool registration, Zod 4 schemas
- `typescript/types/` - ToolContext, ContentItem, protocol types, schema utilities
- `typescript/errors/` - Complete error hierarchy with constructor signatures
- `typescript/middleware/` - MCP middleware and HTTP hooks via app.elysia
- `typescript/server/` - Low-level MCPServer class for custom transports
- `typescript/transports/` - stdio and HTTP transport modes
- `typescript/settings/` - MCPSettings, environment variables, configuration
## Design Decisions
### Options Object Pattern
TypeScript uses options objects for error constructors (vs Python positional args):
```typescript
throw new ContextRequiredToolError('Message', {
additionalPromptContent: 'Please specify...', // required
developerMessage: 'debug info', // optional
});
```
### HTTP Hooks via app.elysia
Clean separation - MCPApp handles MCP, app.elysia handles HTTP:
```typescript
app.elysia.onRequest(({ request }) => { ... });
```
### Runtime Tool Registration
materializeTool() creates tool objects for runtime addition:
```typescript
const tool = materializeTool({ name, input, handler });
await app.tools.add(tool);
```
## Stack
Bun 1.3.x + Elysia 1.3.x + Zod 4.x + TypeScript 5.9.x
## Related
- Python SDK docs: /references/mcp/python/
- Depends on: #XX (Python error hierarchy improvements) - for consistent error docs
TheMostlyGreat
force-pushed
the
docs/typescript-sdk-reference
branch
from
5e6dc25 to
4cf8857
Compare
evantahler
requested changes
Dec 21, 2025
Contributor
evantahler
left a comment
evantahler
left a comment
There was a problem hiding this comment.
This is much better than last time! Some blockers below, but nothing structural!
| @@ -0,0 +1,491 @@ | |||
| --- | |||
| title: "Arcade MCP (MCP Server SDK) - TypeScript Overview" | |||
| description: "Build MCP servers with TypeScript, Bun, Elysia, and Zod 4" | |||
Contributor
There was a problem hiding this comment.
Meta question: There do exist good MCP frameworks in TS. Should we make our own from scratch, or should our stuff be a plugin to an existing one?
Author
There was a problem hiding this comment.
great fucking question. say more. walk me through it
Comment on lines
14
to
16
| ```bash | ||
| bun add arcade-mcp | ||
| ``` |
Contributor
There was a problem hiding this comment.
Open Question: we use bun internally, but docs/demos might still want to use npm/pnpm?
Comment on lines
42
to
43
| // Auth providers | ||
| import { Google, GitHub, Slack } from 'arcade-mcp/auth'; |
Contributor
There was a problem hiding this comment.
Note: all of these auth providers (and error adaptors below) only exist today in python. We will need to copy their configs over
Comment on lines
58
to
64
| app.tool('greet', { | ||
| description: 'Greet a person by name', | ||
| input: z.object({ | ||
| name: z.string().describe('The name of the person to greet'), | ||
| }), | ||
| handler: ({ input }) => `Hello, ${input.name}!`, | ||
| }); |
Contributor
There was a problem hiding this comment.
For a quick start, I think I'd rather have the expanded syntax to make the steps more clear:
// make the tool
const GreetTool = new Tool(...);
// add the tool to the server
app.addTool(GreetTool)
Comment on lines
120
to
121
| /** Transport type: 'stdio' for Claude Desktop, 'http' for web */ | ||
| transport?: 'stdio' | 'http'; |
Contributor
There was a problem hiding this comment.
I agree we can skip SSE now!
| // server.ts | ||
| import * as mathTools from './tools/math'; | ||
|
|
||
| app.addToolsFromModule(mathTools); |
Contributor
There was a problem hiding this comment.
Suggested change
| app.addToolsFromModule(mathTools); | |
| app.add(mathTools); |
The "module" concept is confusing and not nessiscary in TS
| app.addToolsFromModule(mathTools); | ||
| ``` | ||
|
|
||
| Tool names are inferred from export names (`add`, `multiply`). Override with explicit `name` if needed: |
Contributor
There was a problem hiding this comment.
No, I don't like this. Tools should have a name property. Imports get renamed and mangled all the time in TS
|
|
||
| ```typescript | ||
| export const calculator = tool({ | ||
| name: 'basic-calculator', // explicit name overrides 'calculator' |
Contributor
There was a problem hiding this comment.
This should be required
Comment on lines
356
to
357
| requiresAuth: Google({ scopes: ['profile'] }), | ||
| requiresSecrets: ['API_KEY'] as const, // as const enables type-safe getSecret() |
Comment on lines
384
to
385
| handler: ({ input, getMetadata }) => { | ||
| const sessionId = getMetadata('sessionId'); // string | undefined |
Contributor
There was a problem hiding this comment.
What is metadata? I think this is a new concept
- Overview: Clarify tool() vs app.tool() usage, add curl comment - Transports: Fix Windows path, clarify SSE flow, Docker healthcheck - Server: Clarify WHATWG streams, add catalog.add() callout - Middleware: Add execution order note, clarify hooks, fix auth example - Types: Add AuthInfo.userInfo comment, explain as const, dedupe ContentItem
- overview: clarify Arcade as hosted auth service - overview: de-emphasize tool() wrapper, link to Types page - transports: note SSE is handled automatically by SDK - middleware: clarify when to use middleware vs app.onRequest() - types: add Quick Reference table for ToolContext - settings: explain MCP_* vs ARCADE_* env var naming convention
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Complete TypeScript SDK reference documentation with feature parity to Python SDK.
New Pages
overview/- MCPApp, tool registration, Zod 4 schemastypes/- ToolContext, protocol types, schema utilitieserrors/- Complete hierarchy with constructor signaturesmiddleware/- MCP + HTTP hooks viaapp.elysiaserver/- Low-level MCPServer for custom transportstransports/- stdio and HTTP modessettings/- Configuration and environmentDesign Decisions
Options Object Pattern
TypeScript uses options objects for error constructors (vs Python positional args):
HTTP Hooks via app.elysia
Clean separation - MCPApp handles MCP, app.elysia handles HTTP:
Runtime Tool Registration
Stack
Bun 1.3.x + Elysia 1.3.x + Zod 4.x + TypeScript 5.9.x
Related
/references/mcp/python/Note
Adds a complete TypeScript SDK documentation set and aligns Python docs with the latest server lifecycle and configuration.
overview,server,transports,middleware,types,errors,settings, andexamplesunderapp/en/references/mcp/typescript/with navigation via/_meta.tsxserver._start/_stoptoserver.start/stop; update Claude Desktop setup toarcade configure claudetypescriptinapp/en/references/mcp/_meta.tsxpublic/llms.txt: refresh git-sha and add links to new TypeScript reference pagesWritten by Cursor Bugbot for commit 5657da3. This will update automatically on new commits. Configure here.