Skip to main content
Glama
Gwyn-Ahchoo

my-mcp-server

by Gwyn-Ahchoo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

TypeScript MCP Server 보일러플레이트

TypeScript MCP SDK를 활용하여 Model Context Protocol (MCP) 서버를 빠르게 개발할 수 있는 보일러플레이트 프로젝트입니다.

📁 프로젝트 구조

typescript-mcp-server-boilerplate/
├── src/
│   └── index.ts          # MCP 서버 메인 진입점
├── build/                # 컴파일된 JavaScript 파일 (빌드 후 생성)
├── package.json          # 프로젝트 의존성 및 스크립트
├── tsconfig.json         # TypeScript 설정
└── README.md            # 프로젝트 문서

Related MCP server: TypeScript MCP Server Boilerplate

🚀 시작하기

1. 의존성 설치

npm install

2. 서버 이름 설정

src/index.ts 파일에서 서버 이름을 수정하세요:

const server = new McpServer({
    name: 'typescript-mcp-server', // 여기를 원하는 서버 이름으로 변경
    version: '1.0.0',
    // 활성화 하고자 하는 기능 설정
    capabilities: {
        tools: {},
        resources: {}
    }
})

💡 팁: 현재 보일러플레이트에는 이미 계산기와 인사 도구, 그리고 서버 정보 리소스가 예시로 구현되어 있습니다.

3. 빌드

npm run build

4. 실행

node build/index.js

빌드가 성공하면 build/ 디렉토리에 컴파일된 JavaScript 파일이 생성되고, 서버가 MCP 클라이언트의 연결을 대기합니다.

🛠️ 개발 가이드

MCP 도구(Tool) 추가하기

MCP 서버에 새로운 도구를 추가하려면 server.tool() 메서드에 Zod 스키마를 직접 정의하여 등록합니다:

import { z } from 'zod'

// 계산기 도구 추가
server.tool(
    'calculator',
    {
        operation: z
            .enum(['add', 'subtract', 'multiply', 'divide'])
            .describe('수행할 연산 (add, subtract, multiply, divide)'),
        a: z.number().describe('첫 번째 숫자'),
        b: z.number().describe('두 번째 숫자')
    },
    async ({ operation, a, b }) => {
        // 연산 수행
        let result: number
        switch (operation) {
            case 'add':
                result = a + b
                break
            case 'subtract':
                result = a - b
                break
            case 'multiply':
                result = a * b
                break
            case 'divide':
                if (b === 0) throw new Error('0으로 나눌 수 없습니다')
                result = a / b
                break
            default:
                throw new Error('지원하지 않는 연산입니다')
        }

        const operationSymbols = {
            add: '+',
            subtract: '-',
            multiply: '×',
            divide: '÷'
        } as const

        const operationSymbol =
            operationSymbols[operation as keyof typeof operationSymbols]

        return {
            content: [
                {
                    type: 'text',
                    text: `${a} ${operationSymbol} ${b} = ${result}`
                }
            ]
        }
    }
)

더 복잡한 도구 예시

// 날씨 정보 조회 도구
server.tool(
    'get_weather',
    {
        city: z.string().describe('날씨를 조회할 도시명'),
        unit: z
            .enum(['celsius', 'fahrenheit'])
            .optional()
            .default('celsius')
            .describe('온도 단위 (기본값: celsius)')
    },
    async ({ city, unit }) => {
        try {
            // 실제 날씨 API 호출 로직 (예시)
            const weatherData = await fetchWeatherData(city, unit)

            return {
                content: [
                    {
                        type: 'text',
                        text: `${city}의 현재 날씨:
온도: ${weatherData.temperature}°${unit === 'celsius' ? 'C' : 'F'}
날씨: ${weatherData.condition}
습도: ${weatherData.humidity}%
풍속: ${weatherData.windSpeed}km/h`
                    }
                ]
            }
        } catch (error) {
            throw new Error(
                `날씨 정보를 가져올 수 없습니다: ${(error as Error).message}`
            )
        }
    }
)

// 도우미 함수
async function fetchWeatherData(city: string, unit: string) {
    // 실제 날씨 API 호출 구현
    // 여기서는 예시 데이터 반환
    return {
        temperature: unit === 'celsius' ? 22 : 72,
        condition: '맑음',
        humidity: 65,
        windSpeed: 12
    }
}

리소스 추가하기

MCP 서버에 리소스를 추가하여 외부 데이터나 파일에 대한 접근을 제공할 수 있습니다:

// 리소스 등록
server.resource(
    'example-file',
    'file://example.txt',
    {
        name: '예시 텍스트 파일',
        description: '예시 텍스트 파일 설명',
        mimeType: 'text/plain'
    },
    async () => {
        return {
            contents: [
                {
                    uri: 'file://example.txt',
                    mimeType: 'text/plain',
                    text: '예시 파일 내용입니다.'
                }
            ]
        }
    }
)

// 동적 리소스 예시
server.resource(
    'app-settings',
    'config://settings',
    {
        name: '애플리케이션 설정',
        description: '애플리케이션의 현재 설정 정보',
        mimeType: 'application/json'
    },
    async () => {
        const settings = {
            theme: 'dark',
            language: 'ko-KR',
            notifications: true,
            lastUpdated: new Date().toISOString()
        }

        return {
            contents: [
                {
                    uri: 'config://settings',
                    mimeType: 'application/json',
                    text: JSON.stringify(settings, null, 2)
                }
            ]
        }
    }
)

📦 주요 의존성

  • @modelcontextprotocol/sdk: MCP 프로토콜 구현을 위한 공식 SDK

  • zod: TypeScript 우선 스키마 검증 라이브러리

  • typescript: TypeScript 컴파일러

🔧 스크립트

  • npm run build: TypeScript를 JavaScript로 컴파일하고 실행 권한 설정

📋 사용 예시

완전한 서버 예시

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
import { z } from 'zod'

// 서버 생성
const server = new McpServer({
    name: 'my-mcp-server',
    version: '1.0.0',
    capabilities: {
        tools: {},
        resources: {}
    }
})

// 간단한 인사 도구
server.tool(
    'greet',
    {
        name: z.string().describe('인사할 사람의 이름'),
        language: z
            .enum(['ko', 'en'])
            .optional()
            .default('ko')
            .describe('인사 언어 (기본값: ko)')
    },
    async ({ name, language }) => {
        const greeting =
            language === 'ko' ? `안녕하세요, ${name}님!` : `Hello, ${name}!`

        return {
            content: [
                {
                    type: 'text',
                    text: greeting
                }
            ]
        }
    }
)

// 시스템 정보 리소스
server.resource(
    'system-info',
    'system://info',
    {
        name: '시스템 정보',
        description: '서버의 현재 상태 및 시스템 정보',
        mimeType: 'application/json'
    },
    async () => {
        const systemInfo = {
            server: 'my-mcp-server',
            version: '1.0.0',
            timestamp: new Date().toISOString(),
            uptime: process.uptime()
        }

        return {
            contents: [
                {
                    uri: 'system://info',
                    mimeType: 'application/json',
                    text: JSON.stringify(systemInfo, null, 2)
                }
            ]
        }
    }
)

// 서버 시작
async function main() {
    const transport = new StdioServerTransport()
    await server.connect(transport)
    console.error('MCP 서버가 시작되었습니다')
}

main().catch(console.error)

🔧 Cursor MCP 연결

개발한 MCP 서버를 Cursor에서 테스트할 수 있습니다:

설정 파일 수정

./.cursor/mcp.json 파일을 편집합니다:

{
    "mcpServers": {
        "typescript-mcp-server": {
            "command": "node",
            "args": ["/ABSOLUTE/PATH/TO/YOUR/PROJECT/build/index.js"]
        }
    }
}

주의: 절대 경로를 사용해야 합니다. pwd 명령어로 현재 경로를 확인하세요.

테스트 명령어

Cursor MCP에서 다음과 같이 테스트해볼 수 있습니다:

  • "5 더하기 3은 얼마야?" (계산기 도구 테스트)

  • "안녕하세요 라고 인사해줘" (인사 도구 테스트)

  • 서버 정보 리소스 조회

🔗 참고 자료

📄 라이선스

MIT

Available Tools

8 tools
calculateA

두 숫자와 연산자를 입력하면 사칙연산 결과를 반환합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
operatorYes연산자 (+, -, *, /)
aYes첫 번째 숫자
bYes두 번째 숫자

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes계산 결과

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description covers main behavior but does not mention edge cases like division by zero, overflow, or rounding.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no redundancy, front-loaded with key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with full schema and output schema, description is adequate. Could improve by noting error handling or return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear parameter descriptions. The description adds no additional meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it performs basic arithmetic with two numbers and an operator, using specific verb+resource. Sibling tools are unrelated, so no confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when or when not to use. While the tool is simple, the description omits any context about alternatives or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate-imageB

HuggingFace Inference API(FLUX.1-schnell)로 텍스트 프롬프트로부터 이미지를 생성합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes이미지 생성 프롬프트
num_inference_stepsNo추론 스텝 수 (1~10, 기본값: 4)

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions the specific model and API, but omits important behavioral traits such as rate limits, costs, output format, failure modes, or any constraints beyond the parameter schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence with no redundancy. It could be improved with more structure, but it remains concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description does not mention the return value (e.g., image format, URL). Given the tool generates images, this is a significant gap. The description also lacks context about the API's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the description does not need to add meaning. However, it adds no extra context beyond what is already in the schema, so it meets the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (generate image), the resource (text prompt), and the method (HuggingFace Inference API with FLUX.1-schnell). It is distinct from sibling tools which are unrelated tasks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for generating images from prompts, but provides no explicit guidance on when to use or not use this tool, nor any alternatives. Given sibling tools are distinct, confusion is minimal, but guidance is lacking.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

geocode_cityB

도시 이름을 입력하면 위도/경도 좌표를 반환합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
cityYes검색할 도시 이름 (예: 서울, Tokyo, Paris)
languageNo검색 언어 (기본값: ko)ko

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes도시 좌표 결과

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the input and output without mentioning any constraints, limitations, or side effects (e.g., only supports certain city names?). This lack of context is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that efficiently communicates the primary function. It is not verbose, but could potentially include more details without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 parameters, output schema exists), the description covers the basic purpose but lacks behavioral and usage context. It is minimally complete but leaves room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (both city and language have descriptions). The tool description adds minimal value beyond the schema, merely summarizing the input as 'city name'. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool converts a city name to latitude/longitude coordinates, using a specific verb ('반환합니다') and resource ('위도/경도 좌표'). It is distinct from sibling tools like get_weather or get_air_quality, which involve city data but have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives or when not to use it. Even though sibling tools are not directly similar, the description does not provide any context for appropriate usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_air_qualityA

위도와 경도를 입력하면 미세먼지(PM10) 및 초미세먼지(PM2.5) 정보를 반환합니다. days=1이면 현재 값, days>1이면 일별 평균 예보를 반환합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
latitudeYes위도 (-90 ~ 90)
longitudeYes경도 (-180 ~ 180)
daysNo조회할 일수 (1: 현재값, 2~7: 일별 평균 예보, 기본값: 1)

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes대기질 정보

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavioral traits. It explains that days=1 returns current values and days>1 returns daily average forecasts, which is key behavior. However, it does not mention data source, update frequency, coordinate validation, or potential errors. The disclosure is adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, with the first sentence stating the primary function and the second explaining the effect of the 'days' parameter. Every sentence is essential and adds value. It is front-loaded and avoids unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists (reducing the need to explain return values), the description covers the core functionality well. It explains the difference between current and forecast data. However, it could be more complete by mentioning any limitations (e.g., geographic coverage) or how it compares to the sibling 'get_weather'. Overall, fairly complete for a tool with three parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides full descriptions for all three parameters (100% coverage). The description repeats the distinction for the 'days' parameter (1 vs. >1) that is already in the schema. Thus, the description adds minimal semantic value beyond what the schema provides, earning a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns PM10 and PM2.5 air quality data based on latitude and longitude. It specifies the resource (air quality) and the verb (returns), making the purpose clear. However, it does not explicitly differentiate from the sibling tool 'get_weather', which might have overlapping functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the behavior for different 'days' values (current vs. forecast), which provides implicit usage context. However, it does not offer explicit guidance on when to use this tool instead of alternatives like 'get_weather', nor does it mention any prerequisites or conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_weatherB

위도와 경도를 입력하면 현재 날씨 정보를 반환합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
latitudeYes위도 (-90 ~ 90)
longitudeYes경도 (-180 ~ 180)

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes현재 날씨 정보

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, and the description only says 'returns current weather information.' It does not disclose important behavioral traits such as data source, update frequency, caching behavior, or what happens with invalid coordinates (though schema provides range constraints).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the tool's purpose without any filler. Every word is necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and presence of an output schema (implied by 'Has output schema: true'), the description covers the core functionality. Minor gaps like unit specification (Celsius/Fahrenheit) or time of data are likely addressed in output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with descriptions and ranges for both parameters. The description adds no additional meaning beyond 'latitude and longitude' already implied. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns current weather based on latitude and longitude, using specific verb '반환합니다' (returns) and resource '현재 날씨 정보' (current weather info). It distinguishes from siblings like geocode_city and get_air_quality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives (e.g., geocode_city for city-based queries, get_air_quality for air quality). It lacks when-not-to-use or contextual cues.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

greetA

이름과 언어를 입력하면 인사말을 반환합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes인사할 사람의 이름
languageNo인사 언어 (기본값: en)en

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes인사말

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It states the core behavior (returns a greeting) but does not disclose details like output formatting, error handling, or whether there are side effects. For a simple tool, this is acceptable but not exceptional.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that covers the tool's purpose without any extraneous words. It is front-loaded with the core action and efficiently communicates the essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with a complete input schema and an output schema, the description is sufficient. It explains the function clearly, and the remaining details are covered by the structured fields, leaving no significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides complete descriptions for both parameters (name, language) with enums and defaults. The description merely restates that they are inputs and does not add additional semantic context beyond the schema, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a greeting based on a name and language, using a specific verb (반환합니다) and a clear resource (greeting). This is distinct from sibling tools like geocode or get-weather, making its purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a greeting is needed, but it does not explicitly state when to use this tool versus alternatives. Since sibling tools are unrelated, no exclusions are necessary, but explicit guidance is absent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lunar_to_solarA

음력 날짜를 입력하면 양력 날짜를 반환합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
yearYes음력 연도 (예: 2026)
monthYes음력 월 (1~12)
dayYes음력 일 (1~30)
intercalationNo윤달 여부 (기본값: false)

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes양력 날짜 결과

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It only states the conversion but lacks details on supported date ranges, error handling, or calendar system (e.g., Chinese vs Korean lunar). Minimal behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single concise sentence with no wasted words. Front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists but is not shown; description is minimal. It covers the core conversion but omits constraints like valid year range, intercalation handling, or regional variations. Adequate but incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear parameter descriptions. The tool description adds no additional meaning beyond what the schema already provides, so baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool converts a lunar date to a solar date, using a specific verb and resource. It distinguishes from sibling 'solar_to_lunar', which does the reverse.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a lunar date needs conversion, but does not explicitly state when to use or not use it, nor does it mention alternatives like 'solar_to_lunar'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

solar_to_lunarA

양력 날짜를 입력하면 음력 날짜를 반환합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
yearYes양력 연도 (예: 2026)
monthYes양력 월 (1~12)
dayYes양력 일 (1~31)

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes음력 날짜 결과

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden for behavioral disclosure. It only states the basic function without mentioning any limitations, error handling, or side effects. For example, it does not specify valid date ranges or behavior for invalid dates, which is a significant gap for a conversion tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that efficiently conveys the tool's purpose without any unnecessary words. Every word is essential, and the information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple conversion tool with a well-defined schema and an existing output schema, the description is minimal but sufficient. However, it does not address potential caveats like date range constraints or error conditions, which a complete guide might include. Contextually adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but the tool description adds no extra meaning to the parameters beyond the schema field descriptions (e.g., year, month, day). Baseline 3 is appropriate as the schema already documents the parameters adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Input a solar date and returns a lunar date' clearly states the tool's function using a specific verb ('converts') and resource ('solar date to lunar date'). It effectively distinguishes the tool from its sibling 'lunar_to_solar', which performs the reverse operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: when a conversion from solar to lunar calendar is needed. Although it does not explicitly state when not to use it or mention alternatives, the sibling tool 'lunar_to_solar' is the only other date conversion tool, making the use case clear. Lacks explicit guidance but adequate for the task.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv1.0.0
    • First observedcalculate
    • First observedgenerate-image
    • First observedgeocode_city
    • First observedget_air_quality
    • First observedget_weather
    • First observedgreet
    • First observedlunar_to_solar
    • First observedsolar_to_lunar
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 8 tools

Disambiguation5/5

Each tool addresses a completely different functionality (calculation, image generation, geocoding, air quality, weather, greeting, lunar-solar conversion), so there is no overlap or ambiguity.

Naming Consistency3/5

Tool names mix styles: some are simple verbs (calculate, greet), some are verb_noun (geocode_city, generate-image), and some are noun_to_noun (lunar_to_solar, solar_to_lunar). No consistent pattern.

Tool Count3/5

At 8 tools, the count is reasonable, but the server lacks a focused domain; it feels like a random collection of utilities rather than a coherent service.

Completeness2/5

The tools cover only minimal facets of their respective domains (e.g., weather: only current conditions; air quality: only PM; lunar: only conversion). No update, delete, or broader lifecycle operations exist.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • TypeScript MCP Server

    ashotchumore
    F
    license
    Not graded
    quality
    D
    maintenance
    A boilerplate project for quickly developing Model Context Protocol (MCP) servers using TypeScript, with example tools (calculator, greet) and resources (server info) pre-implemented.
    25 npm
    -

  • TypeScript MCP Server

    kimhailey
    F
    license
    A
    quality
    D
    maintenance
    A boilerplate for building MCP servers using TypeScript, with example tools like calculator and greet, plus resource support.
    6
    -

  • toni-mcp-server

    toni0402-han
    F
    license
    B
    quality
    D
    maintenance
    A TypeScript MCP server boilerplate providing example tools and resources for rapid development and testing of Model Context Protocol servers.
    7
    -

  • TypeScript MCP Server

    devbrother2024
    F
    license
    Not graded
    quality
    D
    maintenance
    Provides a starting template for building MCP servers with TypeScript, including examples of tools and resources to accelerate development.
    -