Skip to main content
Glama
enesjakozh
alejandro-ao

MCP Server Example

by alejandro-ao
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

MCP 서버 예제

이 저장소에는 교육용 모델 컨텍스트 프로토콜(MCP) 서버 구현이 포함되어 있습니다. 이 코드는 다양한 LLM 클라이언트와 통합 가능한 기능적인 MCP 서버를 구축하는 방법을 보여줍니다.

전체 튜토리얼을 따라하려면 YouTube 비디오 튜토리얼을 참조하세요.

MCP란 무엇인가요?

MCP(Model Context Protocol)는 애플리케이션이 LLM에 컨텍스트를 제공하는 방식을 표준화하는 개방형 프로토콜입니다. MCP는 AI 애플리케이션의 USB-C 포트와 같습니다. AI 모델을 다양한 데이터 소스 및 도구에 연결하는 표준화된 방식을 제공합니다.

MCP 다이어그램

주요 이점

  • LLM이 직접 연결할 수 있는 미리 구축된 통합 목록이 점점 늘어나고 있습니다.

  • LLM 공급자와 공급업체 간 전환의 유연성

  • 인프라 내에서 데이터를 보호하기 위한 모범 사례

Related MCP server: Optimized Memory MCP Server V2

아키텍처 개요

MCP는 호스트 애플리케이션이 여러 서버에 연결할 수 있는 클라이언트-서버 아키텍처를 따릅니다.

  • MCP 호스트 : MCP를 통해 데이터에 액세스하려는 Claude Desktop, IDE 또는 AI 도구와 같은 프로그램

  • MCP 클라이언트 : 서버와 1:1 연결을 유지하는 프로토콜 클라이언트

  • MCP 서버 : 표준화된 모델 컨텍스트 프로토콜을 통해 특정 기능을 노출하는 경량 프로그램

  • 데이터 소스 : MCP 서버가 액세스할 수 있는 로컬(파일, 데이터베이스) 및 원격 서비스(API)

핵심 MCP 개념

MCP 서버는 세 가지 주요 유형의 기능을 제공할 수 있습니다.

  • 리소스 : 클라이언트가 읽을 수 있는 파일 유형의 데이터(API 응답이나 파일 콘텐츠 등)

  • 도구 : LLM에서 호출할 수 있는 기능(사용자 승인 필요)

  • 프롬프트 : 사용자가 특정 작업을 수행하는 데 도움이 되는 미리 작성된 템플릿

시스템 요구 사항

  • Python 3.10 이상

  • MCP SDK 1.2.0 이상

  • uv 패키지 관리자

시작하기

uv 패키지 관리자 설치

MacOS/Linux의 경우:

지엑스피1

uv 명령이 인식되도록 터미널을 다시 시작하세요.

프로젝트 설정

  1. 프로젝트를 생성하고 초기화합니다.

# Create a new directory for our project
uv init mcp-server
cd mcp-server

# Create virtual environment and activate it
uv venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate

# Install dependencies
uv add "mcp[cli]" httpx

  1. 서버 구현 파일을 만듭니다.

touch main.py

서버 실행

  1. MCP 서버를 시작합니다.

uv run main.py

  1. 서버가 시작되고 연결을 수락할 준비가 됩니다.

Claude Desktop에 연결

  1. 공식 웹사이트에서 Claude Desktop을 설치하세요

  2. MCP 서버를 사용하도록 Claude Desktop을 구성하세요.

~/Library/Application Support/Claude/claude_desktop_config.json 편집합니다.

{
    "mcpServers": {
        "mcp-server": {
            "command": "uv",  # It's better to use the absolute path to the uv command
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/YOUR/mcp-server",
                "run",
                "main.py"
            ]
        }
    }
}

  1. Claude Desktop을 다시 시작하세요

문제 해결

Claude Desktop에서 귀하의 서버를 선택하지 않는 경우:

  1. 구성 파일 경로 및 권한을 확인하세요

  2. 구성의 절대 경로가 올바른지 확인하세요

  3. UV가 제대로 설치되고 접근 가능한지 확인하세요.

  4. 오류 메시지가 있는지 Claude Desktop 로그를 확인하세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 라이선스 파일을 참조하세요.

Available Tools

1 tool
get_docsA

Search the latest docs for a given query and library. Supports langchain, openai, and llama-index.

Args: query: The query to search for (e.g. "Chroma DB") library: The library to search in (e.g. "langchain")

Returns: Text from the docs

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
libraryYes

TDQS

A4.3/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 for behavioral disclosure. It notes that the tool searches 'latest docs' and returns text, implying a read-only operation, but does not mention potential network dependency, error cases, or any side effects. This is adequate but not rich.

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 concise and well-structured: a one-sentence purpose statement followed by clear Args/Returns sections. Every sentence adds value, and information is front-loaded.

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 2-parameter tool with no output schema, the description provides sufficient context: purpose, supported libraries, parameter guidance, and return type. It lacks explicit error handling or formatting details, but these are not critical for this simple search tool.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must fully explain the parameters. It does so effectively with an Args section providing both meaning and examples for 'query' and 'library', plus listing supported library values in the main description.

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's function: 'Search the latest docs for a given query and library.' It specifies the resource (docs), the verb (search), and scope (latest), and distinguishes from sibling Chroma DB tools by focusing on doc search for specific libraries.

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 indicates when to use the tool (when searching docs for langchain, openai, or llama-index) through the list of supported libraries. However, it lacks explicit exclusions or alternative tool references, so it doesn't fully meet the 'when-not/alternatives' criterion.

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. 1 tool update
    • First observedget_docs
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 1 tool

Disambiguation5/5

With only one tool, there is no possibility of ambiguity or overlap between tools. The tool has a single, clear purpose of searching documentation for specific libraries.

Naming Consistency5/5

The single tool name 'get_docs' follows a clear verb_noun pattern. Since there is only one tool, consistency is inherently perfect with no deviations to evaluate.

Tool Count2/5

A single tool is too few for most server purposes, as it severely limits functionality and scope. This feels thin and incomplete for a documentation search server, which might benefit from additional tools like browsing documentation structure or getting library lists.

Completeness2/5

The tool surface is severely incomplete for a documentation search domain. It only supports searching text, with no tools for browsing, listing available libraries, or accessing documentation metadata, creating significant gaps that will hinder agent workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches