Skip to main content
Glama
toni0402-han

toni-mcp-server

by toni0402-han
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: Starter MCP Server

🚀 시작하기

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

7 tools
calcB

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

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

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes계산 결과

TDQS

B3.1/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 behavioral burden, yet it only says a result is returned. It does not disclose behavior for division by zero, invalid operators, numeric limits, or whether failures are surfaced as errors — meaningful gaps for a mutation-free but error-prone computation tool.

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?

A single efficient sentence with the input list preceding the outcome, which is appropriately front-loaded. It is slightly generic ('사칙연산' without enumerating operators) but wastes no 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?

For a simple three-parameter pure computation tool with a fully documented schema and an output schema, the description is sufficient to call it correctly. Error and edge-case behavior is left implicit, which is the only notable gap.

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% and all three parameters are documented in the schema, so the baseline is 3. The description restates 'two numbers and an operator' without adding format, range, or operator-set detail beyond the enum already present in the schema.

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?

States a specific action (returns arithmetic results) with concrete inputs (two numbers and an operator), so an agent immediately knows what it computes. No sibling tool overlaps with it, so sibling differentiation is unnecessary, but the description doesn't mention that it covers exactly +, -, *, / beyond the name 'calc'.

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?

There is no explicit statement of when to use this tool versus alternatives, prerequisites, or edge-case handling. Usage is only implied by the description's mention of inputs and a returned result.

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

generate-imageB

텍스트 프롬프트를 입력하면 HuggingFace FLUX.1-schnell 모델로 이미지를 생성해 반환합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes이미지 생성 프롬프트 (영어 권장)
num_inference_stepsNo추론 스텝 수 (기본값: 4, 범위: 1~10). 높을수록 품질이 좋아지지만 느려집니다.

TDQS

B3.1/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 behavioral burden. It valuably discloses the backing model (FLUX.1-schnell), but says nothing about return format (URL, base64, file path), generation latency, cost, determinism/seed behavior, or failure modes for rejected prompts.

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 tight sentence with no filler, front-loading the input (text prompt) and the output (generated image). Every clause earns its place.

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?

With no output schema and no annotations, the description should at minimum say how the image comes back, and it doesn't. The model name and input/output framing make it minimally viable for a two-parameter tool, but the return contract remains unspecified.

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%, with both prompt and num_inference_steps documented in the schema including defaults and ranges, so the baseline is 3. The description only alludes to the prompt ('텍스트 프롬프트를 입력하면') and adds no meaning beyond the schema—it doesn't even mention the step-count parameter.

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 states a specific verb (생성해 반환합니다) and resource (이미지) plus the underlying model (HuggingFace FLUX.1-schnell), so an agent immediately knows what it does. It does not explicitly contrast with any sibling, but the sibling set (greet, calc, now_time, geocode, get-weather, search_articles) contains no other image tool, so ambiguity is low.

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 only restates the input→output contract ('텍스트 프롬프트를 입력하면 ... 생성해 반환합니다') and gives no when-to-use guidance, no prerequisites, and no alternatives or exclusions. For a single-purpose generator this is tolerable but still leaves usage entirely implicit.

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

geocodeB

도시 이름이나 주소를 입력하면 Nominatim OpenStreetMap API를 통해 위도와 경도 좌표를 반환합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo반환할 최대 결과 수 (기본값: 3, 최대: 10)
queryYes좌표를 조회할 도시 이름 또는 주소 (예: 서울, Tokyo, Paris, 1600 Pennsylvania Ave Washington DC)

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes위도/경도 좌표 결과

TDQS

B3.3/5.0
Behavior3/5

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

No annotations are provided, so the description carries the burden. It usefully discloses the backing service (Nominatim OpenStreetMap), which signals an external API call, but omits any mention of rate limits, latency, failure behavior, or result ordering. It adds context but not rich behavioral detail.

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 well-formed sentence with the input concept front-loaded and the output plus data source trailing. No wasted words.

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?

An output schema exists, so return values need not be explained, and the params are fully covered by the schema. However, with zero annotations the description should say more about external-service behavior (rate limits, failure modes) for a tool that depends on a third-party API.

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 both parameters (query, limit) are already documented in the schema with types, defaults, and bounds. The description only restates the query concept and adds nothing about the limit parameter, so the baseline 3 is appropriate.

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?

States a specific verb+resource: takes a city name or address and returns latitude/longitude coordinates. The purpose is unambiguous and distinct from the unrelated siblings (calc, get-weather, now_time), though it does not explicitly name a sibling it differs from.

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 implies usage by describing the input (city name or address), but gives no explicit when-to-use, when-not-to-use, or alternatives. Nothing addresses error cases (e.g., unresolvable queries) or when to prefer another tool.

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

get-weatherB

위도, 경도, 예보 기간을 입력하면 Open-Meteo API를 통해 현재 날씨와 일별 예보를 반환합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
latitudeYes위도 (예: 37.5665 = 서울)
longitudeYes경도 (예: 126.9780 = 서울)
forecast_daysNo예보 기간 (일 단위, 기본값: 3, 최대: 16)

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes날씨 정보

TDQS

B3.2/5.0
Behavior3/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 does disclose the data source (Open-Meteo) and that both current conditions and a daily forecast are returned, which is genuinely useful context, but it omits auth requirements (none needed), rate limits, units, or timezone handling.

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?

A single efficient sentence that front-loads the inputs and ends with the outcome. No filler, though the input-then-output framing could be trimmed slightly further.

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?

An output schema exists, so return values needn't be described, and the tool is simple (3 flat parameters, 2 required). Combined with the schema documentation and the stated API source, an agent has enough to invoke it correctly; only units/timezone conventions remain unaddressed.

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%, with each parameter (latitude, longitude, forecast_days) already documented including example values, ranges, and defaults. The description merely re-lists the same parameters with no added syntax or format detail, so the baseline of 3 applies.

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?

States a specific verb (반환합니다/returns) and resources (현재 날씨 current weather, 일별 예보 daily forecast) and even names the backing API (Open-Meteo). It is clearly distinguishable from siblings like geocode or now_time, though it never explicitly contrasts itself with any of them.

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 restates the required inputs but gives no when-to-use guidance, no prerequisites, and no exclusions (e.g. when to prefer geocode first to obtain coordinates). Usage is only implied by the parameter list.

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

greetB

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

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

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes인사말

TDQS

B3.4/5.0
Behavior3/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, and it does not state that the tool is a side-effect-free pure lookup or what the greeting output looks like. For a trivial, non-mutating generator the risk is low, but the omission of any behavioral note keeps it at minimum viable.

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 front-loaded sentence with no filler; every clause earns its place and the input-to-output relationship is stated immediately.

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 two-parameter tool with 100% schema coverage and an output schema covering return values, the description supplies enough for correct invocation. Only the absence of any usage/behavioral context keeps it short of a 5.

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%, including the language enum and its default, so the schema already documents both parameters fully. The description only restates that a name and language are input, adding no format or semantic detail beyond the schema.

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 states a specific action and resource: given a name and language, it returns a greeting. That is unambiguous, and the sibling tools (calc, geocode, get-weather, etc.) are in unrelated domains, so no sibling differentiation is required.

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?

It says what inputs are needed but gives no guidance on when to call this versus alternatives, nor any exclusions or prerequisites. With no closely related siblings there is little to disambiguate, but the description offers no usage context at all.

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

now_timeC

나라 이름을 입력하면 해당 나라의 현재 시간을 반환합니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
countryYes현재 시간을 조회할 나라 이름 (예: Korea, Japan, USA, France)

Output Schema

ParametersJSON Schema
NameRequiredDescription
contentYes현재 시간

TDQS

C2.9/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 behavioral burden. It says the tool returns 'current time' but does not disclose timezone semantics (local country time vs UTC), DST handling, behavior for unrecognized country names, or whether any external lookup/rate limit is involved.

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?

A single front-loaded sentence with no filler; the input condition precedes the outcome. It is efficient, though its brevity edges into under-specification rather than tight precision.

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?

The tool is simple (one parameter) and an output schema exists, so return formatting need not be explained. However, with zero annotations and no timezone or error-handling notes, the definition is only minimally adequate for an agent to call it with confidence.

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% and the single 'country' parameter already documents the expected value with examples (Korea, Japan, USA, France). The description adds no format, aliasing, or casing guidance beyond what the schema already says, so the baseline 3 applies.

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 states a specific verb+resource: given a country name, it returns that country's current time. That is clearly distinct from greet/calc/generate-image/search_articles, though it does not explicitly separate itself from the location-flavored sibling get-weather. Clear but without sibling differentiation, so a 4.

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 sentence only restates the input→output relationship; it gives no when-to-use guidance, no prerequisites, and no routing against get-weather, which is the obvious alternative for location-keyed queries. Nothing tells the agent when this tool is the right pick.

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

search_articlesA

텍스트(주제/키워드)를 입력하면 최근 1주일 동안의 관련 뉴스 기사 및 블로그를 검색하여 최신순/정확도순으로 반환합니다. 각 결과에는 클릭 가능한 실제 링크가 포함됩니다.

ParametersJSON Schema
NameRequiredDescriptionDefault
sortNo정렬 기준 (recent: 최신순, relevance: 관련도순, 기본값: recent)recent
countNo반환할 결과 수 (기본값: 10, 최대: 20)
queryYes검색할 텍스트 또는 주제 (예: "AI 반도체", "기후변화", "ChatGPT")
languageNo검색 언어 (ko: 한국어 뉴스, en: 영어 뉴스, 기본값: ko)ko

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 are provided, so the description must carry the behavioral burden. It usefully discloses the 1-week recency window and that results contain clickable real links, but says nothing about auth, rate limits, or result completeness/caps beyond what the schema implies.

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?

Two tight sentences, front-loaded with purpose and scope. Every clause contributes (search input, time window, sort order, link output) with no filler.

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?

An output schema exists, so return-format explanation is unnecessary, and the description covers purpose, recency scope, and output nature. It omits mention of the language and count parameters, but the schema documents those fully.

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 enum values and defaults documented for sort, count, and language, so the schema does the heavy lifting. The description only echoes the sort behavior (latest/relevance) and adds no syntax or format detail 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?

States a precise verb (search) applied to a specific resource (news articles and blogs), and adds scope that constrains the result set to the last week. An agent immediately understands what this tool returns and how it differs from the unrelated utility siblings (greet, calc, geocode, etc.).

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 the use case (text/topic in, recent articles out) but gives no explicit when-to-use or when-not guidance. None of the sibling tools are competing search tools, so there is no alternative to route to, which keeps this from being a critical gap.

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. 7 tool updatesv1.0.0
    • First observedcalc
    • First observedgenerate-image
    • First observedgeocode
    • First observedget-weather
    • First observedgreet
    • First observednow_time
    • First observedsearch_articles
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 7 tools

Disambiguation5/5

Each tool targets a clearly distinct operation: greeting, arithmetic, image generation, time lookup, geocoding, weather, and article search. There is no overlap in purpose, so an agent can select the right tool unambiguously. The geocode/get-weather pair even composes cleanly rather than conflicting.

Naming Consistency2/5

Conventions are mixed: bare words (greet, calc, geocode), kebab-case (generate-image, get-weather), and snake_case (now_time, search_articles). Verb styles also vary, with some names having no verb at all. No single predictable pattern emerges.

Tool Count5/5

Seven tools is well within the healthy 3-15 range and each represents a discrete, self-contained capability. No tool feels redundant or padded, and the set is not so thin that obvious needs are unmet.

Completeness4/5

As a grab-bag of stateless utilities, each tool fully covers its single operation (compute, fetch, generate) with no dead ends, and geocode feeds get-weather. The surface is hard to call complete since there is no defined domain lifecycle, but no major gaps are apparent.

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
    -

  • Starter MCP Server

    YunYouJun
    A
    license
    B
    quality
    D
    maintenance
    A template/boilerplate project for building Model Context Protocol (MCP) servers with TypeScript. Provides a starting point with configuration examples, development tools, and debugging setup.
    2
    1
    MIT

  • TypeScript MCP Server

    jeena-9595
    F
    license
    Not graded
    quality
    D
    maintenance
    A template project for quickly building Model Context Protocol (MCP) servers using TypeScript and the official SDK. It includes pre-configured examples for tools and resources to help developers jumpstart their custom MCP server development.
    25 npm
    -

  • TypeScript MCP Server

    bakcoder
    F
    license
    A
    quality
    D
    maintenance
    A starter project for rapidly developing Model Context Protocol servers using TypeScript and the official SDK. It includes pre-implemented examples of tools and resources to help developers jumpstart their custom MCP server development.
    6
    -