A production-ready TypeScript template for building Model Context Protocol (MCP) servers. Skip the boilerplate and ship working tools to Claude and other MCP clients in minutes.
Working MCP server using the official @modelcontextprotocol/sdk
3 example tools you can use as-is or adapt:
fetch_url — fetch web content with configurable limits and domain blocking
read_file / list_directory — safe filesystem access with path traversal protection
transform_data — convert between JSON, CSV, TSV, Markdown table, and plain text
TypeScript throughout — strict mode, typed inputs/outputs, Zod validation
Error handling patterns — every tool returns a typed ToolResult<T> with ok/error discrimination
Environment-based config — all limits and paths configurable via .env
Structured logging — stderr-only logger (MCP protocol uses stdout)
Test suite — 19 tests with Vitest covering all three tools
Build scripts — npm run build, npm run dev, npm test, npm run typecheck
Related MCP server: MCP Base Server
Node.js 18 or higher
npm 9 or higher
# 1. Install dependencies
npm install
# 2. Configure environment
cp .env.example .env
# Edit .env — at minimum, set FILE_READER_ROOT to a safe directory
# 3. Build
npm run build
# 4. Run
npm startnpm run devUses tsx for live reload — no build step required during development.
Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["/absolute/path/to/mcp-starter-kit/dist/index.js"],
"env": {
"FILE_READER_ROOT": "/path/to/allowed/directory",
"LOG_LEVEL": "info"
}
}
}
}Restart Claude Desktop. Your tools will appear in the tool picker.
Add to .claude/settings.json:
{
"mcpServers": {
"my-server": {
"command": "node",
"args": ["/absolute/path/to/mcp-starter-kit/dist/index.js"]
}
}
}Fetches the text content of a URL.
Parameter | Type | Required | Description |
| string | yes | HTTP or HTTPS URL to fetch |
| object | no | Additional request headers |
| number | no | Request timeout (100–30000ms, default from env) |
Returns the response body, status code, content type, and a truncated flag if the response exceeded FETCH_MAX_BYTES.
Reads a file within the configured FILE_READER_ROOT.
Parameter | Type | Required | Description |
| string | yes | Relative path from root |
|
| no | Encoding (default: utf8) |
| number | no | Max bytes to read (default: 1MB) |
Path traversal (../) is blocked at the resolver level.
Lists files and directories within the configured root.
Parameter | Type | Required | Description |
| string | no | Relative directory path (default: |
| boolean | no | List nested files (default: false) |
Converts data between formats.
Parameter | Type | Required | Description |
| string | yes | Raw input data |
|
| yes | Input format |
|
| yes | Output format |
| boolean | no | Pretty-print JSON (default: true) |
| boolean | no | Include CSV/TSV header row (default: true) |
| string | no | Custom delimiter for CSV/TSV parsing |
All configuration is via environment variables. See .env.example for the full list.
Variable | Default | Description |
|
| Server identity reported to clients |
|
| Server version |
|
| Max response size for web fetcher (bytes) |
|
| Default fetch timeout (ms) |
| (empty) | Comma-separated blocked hostnames |
|
| Root directory for file access |
|
| Max input characters for transformer |
|
| Logging level (debug/info/warn/error) |
Create src/tools/my-tool.ts — export an async function that returns ToolResult<YourType>
Add input/output types to src/types.ts using Zod schemas
Register the tool in src/index.ts with server.tool(name, description, schema, handler)
Write tests in src/tools/my-tool.test.ts
The pattern used by all three example tools:
export async function myTool(input: MyToolInput): Promise<ToolResult<MyToolOutput>> {
// validate, execute, return { ok: true, data: ... } or { ok: false, error: "...", code: "..." }
}mcp-starter-kit/
├── src/
│ ├── index.ts # Server entry point — tool registration
│ ├── config.ts # Environment variable loading
│ ├── logger.ts # Stderr logger
│ ├── types.ts # Shared types and Zod schemas
│ └── tools/
│ ├── web-fetcher.ts
│ ├── web-fetcher.test.ts (add your own)
│ ├── file-reader.ts
│ ├── file-reader.test.ts
│ ├── data-transformer.ts
│ └── data-transformer.test.ts
├── dist/ # Compiled output (after npm run build)
├── .env.example
├── package.json
├── tsconfig.json
└── vitest.config.tsnpm test # Run once
npm run test:watch # Watch modeMIT
Fetch the content of a URL and return it as text. Supports HTTP and HTTPS. Returns the response body, status code, and content type. Binary content (images, PDFs, etc.) is rejected — text and JSON only.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| headers | No | Optional HTTP headers | |
| timeout_ms | No | Request timeout in milliseconds (100–30000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: it returns response body, status code, and content type; rejects binary content; and supports specific protocols. However, it misses details like error handling, rate limits, or authentication needs, which would be useful for a fetch operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and efficiently adds critical details in two sentences. Every sentence earns its place by specifying functionality, protocols, return values, and content restrictions without redundancy, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is mostly complete—it covers purpose, behavior, and limitations. However, it lacks details on error responses or output structure, which would enhance completeness for an agent invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (2 out of 3 parameters have descriptions). The description adds no specific parameter semantics beyond what the schema provides—it mentions URL fetching generally but does not explain headers or timeout usage. With moderate schema coverage, the baseline score of 3 is appropriate as the description does not compensate for gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('fetch the content of a URL') and resource ('URL'), distinguishing it from sibling tools like list_directory, read_file, and transform_data. It specifies the return format ('as text') and protocol support ('HTTP and HTTPS'), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning protocol support and content restrictions ('text and JSON only'), but it does not explicitly state when to use this tool versus alternatives or provide context about prerequisites. It lacks direct guidance on scenarios where this tool is preferred over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files and directories. Paths are relative to the configured root (/app/workspace). Set recursive=true to list all nested files.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Directory path relative to the configured root | . |
| recursive | No | Whether to list files recursively | |
| max_depth | No | Maximum directory depth for recursive listing (default: 3, max: 10) | |
| max_entries | No | Maximum total entries to return (default: 10000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the root path configuration and recursive behavior, but it doesn't cover important aspects like whether this is a read-only operation, potential rate limits, error conditions (e.g., invalid paths), or what the output format looks like (since there's no output schema). For a tool with no annotations, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise and front-loaded: it states the core purpose in the first sentence, followed by key contextual details. Both sentences earn their place by providing essential information without redundancy. It's appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no annotations and no output schema, the description is incomplete. It covers basic purpose and some parameter hints but lacks crucial behavioral details (e.g., safety, errors, output format) and doesn't fully compensate for the missing structured data. For a 4-parameter tool with no annotations or output schema, this description should do more to guide the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema: it mentions the root path context and hints at the 'recursive' parameter's effect. However, it doesn't provide additional semantic context for parameters like 'max_depth' or 'max_entries' that aren't covered in the description. Baseline 3 is appropriate when the schema does most of the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List files and directories.' It specifies the verb ('List') and resource ('files and directories'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'fetch_url' or 'read_file', though the distinction is somewhat implied by the domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context: 'Paths are relative to the configured root (/app/workspace). Set recursive=true to list all nested files.' This gives basic guidance on when to use certain parameters, but it doesn't explicitly state when to use this tool versus alternatives like 'fetch_url' or 'read_file', nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a file from the filesystem. Paths are relative to the configured root directory (/app/workspace). Path traversal (../) is blocked. Use encoding=base64 for binary files.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to the file, relative to the configured root directory | |
| encoding | No | File encoding — use base64 for binary files | utf8 |
| max_bytes | No | Maximum bytes to read (default: 1MB, max: 10MB) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing important behavioral traits: path traversal blocking, root directory context, and encoding recommendations for binary files. It doesn't mention error conditions, permissions, or rate limits, but provides solid operational context for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with zero waste - each sentence provides essential information: core purpose, path constraints, and encoding guidance. Perfectly front-loaded with the main action first, followed by important operational details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read operation with no annotations and no output schema, the description provides good context about path handling and encoding. It could mention what happens with non-existent files or permission errors, but covers the essential operational constraints well given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema - it mentions encoding=base64 for binary files (which is also in the schema) and implies path handling context. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Read a file') and resource ('from the filesystem'), distinguishing it from sibling tools like list_directory (which lists files) or fetch_url (which retrieves from URLs). It provides specific context about path handling that makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use certain options ('use encoding=base64 for binary files') and mentions path traversal restrictions, but doesn't explicitly contrast when to use this tool versus alternatives like fetch_url or transform_data. It gives operational guidance but not sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert data between formats: JSON, CSV, TSV, Markdown table, and plain text summary. Useful for reformatting API responses, preparing data for display, or normalising spreadsheet exports.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | The raw input data to transform | |
| from_format | Yes | Input data format | |
| to_format | Yes | Desired output format | |
| options | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While it mentions what the tool does, it doesn't describe important behavioral aspects like error handling, performance characteristics, rate limits, authentication requirements, or what happens with malformed input. The description is functional but lacks operational transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each earn their place. The first sentence states the core functionality with specific format examples, and the second sentence provides usage contexts. No wasted words, front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no annotations and no output schema, the description is adequate but has clear gaps. It explains what the tool does and when to use it, but doesn't address output format details, error conditions, or behavioral constraints. Given the complexity and lack of structured metadata, more complete operational guidance would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 75% schema description coverage, the baseline is 3. The description doesn't add specific parameter semantics beyond what's in the schema - it mentions format conversions generally but doesn't explain parameter interactions, constraints, or edge cases. The schema already documents parameters well, so the description doesn't compensate for the 25% coverage gap but doesn't need to either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('convert', 'reformat', 'prepare', 'normalise') and resources ('data between formats'), listing all supported formats. It distinguishes this from sibling tools (fetch_url, list_directory, read_file) by focusing on data transformation rather than data retrieval or file operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('useful for reformatting API responses, preparing data for display, or normalising spreadsheet exports'), giving concrete scenarios. However, it doesn't explicitly state when NOT to use it or mention alternatives among sibling tools, which prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0fetch_urllist_directoryread_filetransform_dataScored across 4 tools
Each tool has a clearly distinct purpose: fetch_url handles web content retrieval, list_directory deals with filesystem listing, read_file focuses on file reading, and transform_data manages data format conversion. There is no overlap in functionality, making tool selection straightforward for an agent.
Three tools follow a consistent verb_noun pattern (fetch_url, list_directory, read_file), but transform_data uses a verb_adjective pattern, which is a minor deviation. Overall, the naming is readable and mostly predictable, with only one tool breaking the pattern slightly.
With 4 tools, the server is well-scoped for a starter kit focused on basic web and filesystem operations. Each tool earns its place by covering distinct, essential tasks without being overly sparse or bloated, making it appropriate for its purpose.
The tool set covers core operations for web fetching, filesystem listing, file reading, and data transformation, with no obvious dead ends. However, there are minor gaps, such as no write_file tool for filesystem modifications, which agents might need to work around, but the surface is largely complete for a starter kit.
A simple Typescript MCP server built using the official MCP Typescript SDK and smithery/cli. This…
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
A TypeScript MCP server for Home Assistant, enabling programmatic management of entities, automati…
Cloudflare Workers MCP server: ai-model-router
