DEV Community: sea-turt1e

Building an MCP Server Using My Custom Python Library

sea-turt1e — Thu, 12 Jun 2025 01:00:00 +0000

Introduction

To familiarize myself with the MCP protocol, I implemented an MCP server using a custom Python library.
For the custom library, I utilized the kanjiconv library, which handles Japanese character conversion.
I have implemented this as a standalone MCP server and made it accessible through Claude Desktop.
The kanijconv article is here

What is MCP?

MCP (Model Context Protocol) is an open standard protocol designed to enable AI models to securely interact with external tools and data sources. While there are numerous articles explaining MCP in detail elsewhere, using this protocol allows developers to easily integrate specialized functionality into AI models by providing them with appropriate tools.

What I Created

The GitHub repository for this project is as follows:
https://github.com/sea-turt1e/kanjiconv_mcp

The kanjiconv_mcp implementation provides the following features:

Kanji to Hiragana Conversion: "幽☆遊☆白書は最高の漫画です" → "ゆうゆうはくしょはさいこうのまんがです"
Kanji to Katakana Conversion: "幽☆遊☆白書は最高の漫画です" → "ユウユウハクショハサイコウノマンガデス"
Kanji to Romanized Japanese Conversion: "幽☆遊☆白書は最高の漫画です" → "yuuyuuhakushohasaiikounomangadesu"

Technical Stack

Python 3.13: The Python environment
uv: A high-performance Python package manager
kanjiconv: The Japanese character conversion library
sudachipy: A morphological analysis engine
Docker: Used for containerization to ensure consistent environment setup
MCP SDK: For integration with Claude Desktop

Project Structure

kanjiconv_mcp/
├── main.py                    # Main implementation of the MCP server
├── pyproject.toml            # Project configuration and dependencies
├── requirements.txt          # Pip dependency list
├── Dockerfile               # uv version
├── Dockerfile.pip           # Pip fallback version
├── docker-compose.yml       # Service management configuration
├── docker.sh               # Helper script for Docker operations
├── claude_desktop_config.json    # Example Claude Desktop configuration
|── claude_desktop_config_docker.json # Docker-specific configuration example
└── test_client.py          # Test client for verification

Key Implementation Points

1. Basic MCP Server Architecture

from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import TextContent, Tool

# Create MCP server instance
server = Server("kanjiconv-mcp")

@server.list_tools()
async def list_tools() -> list[Tool]:
    """Returns a list of available tools"""
    return [
        Tool(
            name="convert_to_hiragana",
            description="Convert Japanese text (including kanji) to hiragana",
            inputSchema={
                "type": "object",
                "properties": {
                    "text": {"type": "string", "description": "Japanese text to convert"},
                    "separator": {"type": "string", "default": "/"},
                    # ... other options
                },
                "required": ["text"],
            },
        ),
        # ... other tools
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    """Handles tool invocation"""
    if name == "convert_to_hiragana":
        request = ConvertRequest(**arguments)
        kanji_conv = get_kanji_conv_instance(
            request.separator, 
            request.use_custom_readings, 
            request.use_unidic, 
            request.sudachi_dict_type
        )
        result = kanji_conv.to_hiragana(request.text)
        return [TextContent(type="text", text=result)]

2. Flexible Configuration Options

Each conversion tool supports the following options:

separator: Word separation character (default: "/")
use_custom_readings: Use custom reading dictionary
use_unidic: Enable UniDic usage (for improved accuracy)
sudachi_dict_type: Sudachi dictionary type (options: full/small/core)

3. Environment Standardization via Docker

Main Dockerfile (uv version)

FROM python:3.13-slim-bookworm
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# Install system dependencies
RUN apt-get update && apt-get install -y \
    curl \
    build-essential \
    pkg-config \
    && rm -rf /var/lib/apt/lists/*

# Install Rust
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y \
    && . /root/.cargo/env
ENV PATH="/root/.cargo/bin:$PATH"

ADD . /app

# Configure uv
WORKDIR /app
RUN uv sync --locked

# Download dictionaries
RUN uv run python -m unidic download

COPY main.py ./

EXPOSE 8000

# Set environment variables
ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1

# Run MCP server
CMD ["uv", "run", "python", "main.py"]

Fallback Dockerfile (pip version)

FROM python:3.13-slim-bookworm

RUN apt-get update && apt-get install -y \
    curl \
    build-essential \
    pkg-config \
    git \
    && rm -rf /var/lib/apt/lists/*

RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
ENV PATH="/root/.cargo/bin:$PATH"

WORKDIR /app

COPY requirements.txt ./

RUN pip install --upgrade pip \
    && pip install --no-cache-dir -r requirements.txt

RUN python -m unidic download

COPY main.py ./
COPY pyproject.toml ./

EXPOSE 8000

ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1

CMD ["python", "main.py"]

4. Convenient Helper Script

The docker.sh script simplifies Docker operations:

# Build (tries uv first, then falls back to pip)
./docker.sh build

# Explicitly build with pip version
./docker.sh build-pip

# Run tests
./docker.sh test

# Clean up
./docker.sh clean

Configuration for Claude Desktop

By configuring claude_desktop_config.json as shown below, you can utilize the MCP server with Claude Desktop. (I tested this on a Mac environment.)

Local Execution Version

{
  "mcpServers": {
    "kanjiconv": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/kanjiconv_mcp",
        "run",
        "python",
        "main.py"
      ]
    }
  }
}

Docker Version

{
  "mcpServers": {
    "kanjiconv": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "kanjiconv-mcp:latest"],
      "cwd": "/path/to/kanjiconv_mcp"
    }
  }
}

Development Challenges

1. Rust Dependency Issues

The sudachipy package includes Rust-written components, which made building the Docker image particularly complex. I had to both install the Rust compiler and configure necessary environment variables.

2. Choosing Between `uv` and `pip`

While the latest uv version offers superior performance, it may not be supported on all environments. Therefore, I implemented a build system with fallback functionality to handle such cases.

Practical Usage Examples

You can ask Claude Desktop questions like these:

"It's a beautiful day today" - convert each token separated by "/" to hiragana.

→ "きょう/は/よ/い/てんき/です/ね"

Convert "programming language" to katakana.

→ "プログラミング/ゲンゴ"

Convert "Japanese text processing" to romaji.

→ "nihongo/shori"

Conclusion

In this project, I successfully built an MCP server using my custom Python library.
This experience demonstrated that integrating such custom libraries with LLMs can be implemented more straightforwardly than one might expect.
By leveraging MCP, we can easily add specific functionalities to AI models, so I'm looking forward to developing more such tools in the future.

【kanjiconv】A Python Conversion Library for Converting "Kanji" to "Kana/Romanized" Text, Supporting Proper Nouns

sea-turt1e — Tue, 18 Mar 2025 10:00:00 +0000

Introduction

When processing Japanese text, there are many situations where you need to convert kanji into hiragana, katakana, or romanized text. For instance, when creating educational materials for Japanese learners or preprocessing for speech synthesis. Thus, I developed the Python library "kanjiconv," which allows easy retrieval of kanji readings and pronunciations.

"kanjiconv" is built on the morphological analysis engine SudachiPy and its dictionary SudachiDict. This allows for highly accurate readings, including proper nouns.

Previously, I created a similar library based on mecab-unidic-neologd. However, since neologd has stopped being updated, I developed kanjiconv as an alternative.

※ kanjiconv is licensed under the Apache License 2.0.

GitHub Repositry

GitHub Repositry of this library is here

Installation

Installing kanjiconv

First, install "kanjiconv" using pip:

pip install kanjiconv

Usage

Import and Instance Generation

First, import the library and create an instance of KanjiConv. You can optionally specify a separator (default is "/").

# Import
from kanjiconv import KanjiConv
# Create an instance and specify the separator (e.g., '/')
kanji_conv = KanjiConv(separator="/")

Convert Kanji to Hiragana

text = "幽☆遊☆白書は、最高の漫画デス。"
print(kanji_conv.to_hiragana(text))
# Output: ゆうゆうはくしょ/は/、/さいこう/の/まんが/です/。

Convert Kanji to Katakana

print(kanji_conv.to_katakana(text))
# Output: ユウユウハクショ/ハ/、/サイコウ/ノ/マンガ/デス/。

Convert Kanji to Romanized Text

print(kanji_conv.to_roman(text))
# Output: yuuyuuhakusho/ha/, /saikou/no/manga/desu/.

Change the Separator

# Set the separator to '_'
kanji_conv = KanjiConv(separator="_")
print(kanji_conv.to_hiragana(text))
# Output: ゆうゆうはくしょ_は_、_さいこう_の_まんが_です_。

# Set the separator to none
kanji_conv = KanjiConv(separator="")
print(kanji_conv.to_hiragana(text))
# Output: ゆうゆうはくしょは、さいこうのまんがです。

Conclusion

With "kanjiconv," you can easily convert kanji to hiragana, katakana, or romanized text. It's a handy tool for various applications, such as preprocessing Japanese text or supporting language learning. Give it a try!

License

kanjiconv: Apache License 2.0
SudachiPy: Apache License 2.0
SudachiDict: Apache License 2.0

[Sample Code] Using Amazon Bedrock Claude's ToolUse with AWS SDK for Go v2

sea-turt1e — Tue, 18 Mar 2025 09:00:00 +0000

This time, I will introduce an implementation example of Claude's ToolUse via Amazon Bedrock in Go.

When I searched for sample code online or read AWS documentation, I only found code in Python or Rust, and barely any in Go, which was quite challenging. I hope this helps others facing the same difficulty.

AWS SDK for Go v2

I will use AWS SDK for Go v2 for this tutorial.

Performing this with v1 is quite difficult (probably due to halted development), so I don't recommend it. I initially struggled with v1 due to other constraints, but it didn't work out.

What is ToolUse?

Claude's ToolUse is a feature that allows you to define and call external tools or functions (APIs), thereby extending Claude's capabilities. It is similar to "Function Calling" in GPT. In this sample code, we perform a simple math calculation and return the result in JSON format.

Code

Full Code

The complete code is available here

Code Explanation

Setting Environment Variables

First, set the necessary environment variables in a .env file when using the AWS SDK.

AWS_ACCESS_KEY_ID=your_aws_access_key_id
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key
AWS_REGION=your_aws_region
MODEL_ID=your_model_id

MODEL_ID is the model ID used in the API request, such as "anthropic.claude-3-haiku-20240307-v1:0".

However, you need to allow model access on the AWS console for the model you want to use.

As of 2025/03/15, the claude-3.5-haiku model is only available Cross-Region. To use claude-3.5-haiku, you need to specify "us.anthropic.claude-3-5-haiku-20241022-v1:0".

Loading Environment Variables

The following code is from main.go, which loads the environment variables from the .env file.

func init() {
    if err := godotenv.Load("../../.env"); err != nil {
        log.Fatal("Error loading .env file")
    }
}

Defining Tool Name and Input Schema

Next, set the tool name and input schema to define what data the tool will accept.

var toolName = "math_tool"

var itemProperties = map[string]interface{}{
    "formula": map[string]interface{}{
        "description": "Formula to be calculated",
        "type":        "string",
    },
    "answer": map[string]interface{}{
        "description": "the answer to the formula",
        "type":        "string",
    },
}

var toolProperties = map[string]interface{}{
    "item": map[string]interface{}{
        "type":       "array",
        "properties": itemProperties,
    },
}

var inputSchema = map[string]interface{}{
    "type": "object",
    "properties": map[string]interface{}{
        "tool": toolProperties,
    },
}

Setting System Instructions and User Message

Next, define the system instructions and user message to specify what task the AI model should perform.

systemInstruction := fmt.Sprintf("Use %s to get the sum of two numbers.", toolName)
system := []types.SystemContentBlock{
    &types.SystemContentBlockMemberText{
        Value: systemInstruction,
    },
}

input := "1 + 2"
userMsg := types.Message{
    Role: types.ConversationRoleUser,
    Content: []types.ContentBlock{
        &types.ContentBlockMemberText{
            Value: input,
        },
    },
}

Defining Tool Configuration

Specify which tool to use.

toolConfig := types.ToolConfiguration{
    Tools: []types.Tool{
        &types.ToolMemberToolSpec{
            Value: types.ToolSpecification{
                InputSchema: &types.ToolInputSchemaMemberJson{
                    Value: document.NewLazyDocument(inputSchema),
                },
                Name: &toolName,
            },
        },
    },
}

Request to Claude

Send the request to Claude using Bedrock Runtime.

output, err := bedrockRuntime.Converse(context.Background(), &bedrockruntime.ConverseInput{
    ModelId:    &modelId,
    Messages:   []types.Message{userMsg},
    System:     system,
    ToolConfig: &toolConfig,
})

Handling the Response

Extract the necessary information from the response.

response, _ := output.Output.(*types.ConverseOutputMemberMessage)
responseContentBlock := response.Value.Content[0]
text, _ := responseContentBlock.(*types.ContentBlockMemberText)
fmt.Printf("Response: %s\n", text.Value)

contentBlock := response.Value.Content[1]
toolUseOutput, _ := contentBlock.(*types.ContentBlockMemberToolUse)
toolUseOutputJson, err := toolUseOutput.Value.Input.MarshalSmithyDocument()
if err != nil {
    log.Fatalf("unable to marshal tool use output, %v", err)
}
fmt.Printf("Tool Use Output: %s\n", toolUseOutputJson)

Conclusion

In this article, I introduced how to use Claude's ToolUse via Amazon Bedrock with AWS SDK for Go v2. Since I'm not an expert in Go, I would appreciate any feedback on improving the code.

Predicting NBA Player Chemistry Using Graph Neural Networks

sea-turt1e — Wed, 08 Jan 2025 03:14:00 +0000

Hello, I’m sea_turt1e.

In this post, I’ll share the process and results of building a machine learning model to predict the chemistry of players in the American professional basketball league, the NBA, which I love.

Overview

Used Graph Neural Networks (GNNs) for chemistry prediction.
Adopted AUC (Area Under the Curve) as the evaluation metric.
The AUC at convergence was approximately 0.73.
Training data covered the 1996–97 to 2021–22 seasons, with the 2022–23 season reserved for testing.

Caution: About NBA

For readers unfamiliar with the NBA, some parts of this post may be difficult to follow. However, you can think of "chemistry" in a more intuitive sense. Additionally, while this post focuses on the NBA, the approach can be applied to other sports or even interpersonal chemistry predictions.

chemistry Prediction Results

Let’s start with the prediction results. I’ll dive into the dataset and technical details later.

explanation of edge and score

In chemistry predictions, red edges indicate good chemistry, black edges indicate moderate chemistry, and blue edges indicate poor chemistry.

The score on the edge represent the chemistry score, ranging from 0 to 1.

chemistry Prediction for Star Players

Here are the chemistry predictions for star players. The graph only includes pairs of players who have never been on the same team.

Looking at the predictions for star players who have never played together, the results may not always align with intuition.

For instance, LeBron James and Stephen Curry displayed excellent synergy during the Olympics, suggesting high chemistry. On the other hand, it’s surprising that Nikola Jokić was predicted to have low chemistry with other players.

chemistry Predictions for Major Trades in the 2022–23 Season

To make the predictions more relatable, I tested chemistry between players involved in actual trades during the 2022–23 season.

Since the 2022–23 season wasn’t included in the training data, predictions aligning with real-world impressions could indicate the model's validity.

The 2022–23 season saw several significant trades.

Here are the predictions for key players such as Kevin Durant, Kyrie Irving, and Rui Hachimura.

The chemistry predictions for their new teams were as follows:

Lakers: Rui Hachimura – LeBron James (Red edge: good chemistry)
Suns: Kevin Durant – Chris Paul (Black edge: moderate chemistry)
Mavericks: Kyrie Irving – Luka Doncic (Blue edge: poor chemistry)

Considering the 2022–23 season’s dynamics, these results seem reasonably accurate.

(Although the situation changed for the Suns and Mavericks in later seasons.)

Technical Details

From here, I’ll explain the technical aspects, including the GNN framework and dataset preparation.

What is a GNN?

A GNN (Graph Neural Network) is a neural network designed to process graph-structured data.

In this model, "chemistry" between players is represented as graph edges, and learning was conducted as follows:

Positive edges: Pairs of players with high assist counts.
Negative edges: Pairs of players with low assist counts.

For negative edges, the model prioritized "teammates with low assist counts" and de-emphasized "players from different teams."

What is AUC?

AUC (Area Under the Curve) refers to the area under the ROC curve and serves as a metric to evaluate model performance.

An AUC closer to 1 indicates higher accuracy. In this study, the model achieved an AUC of about 0.73—a moderately good result.

Learning Curve and AUC Progression

Here are the learning curve and AUC progression from the training process:

Dataset

The primary innovation was in constructing the dataset.

To quantify chemistry, I hypothesized that "high assist counts" indicate good chemistry. Based on this hypothesis, the dataset was structured as follows:

Positive edges: Players with high assist counts.
Negative edges: Players with low assist counts.

Additionally, teammates with low assist counts were explicitly treated as having poor chemistry.

Code Details

All code is available on GitHub.

Following the instructions in the README should allow you to replicate the training process and plot the graphs described here.

https://github.com/sea-turt1e/NBANetwork

Future Prospects

There is still room for improvement, and I aim to achieve the following goals:

Expand the definition of chemistry
- Incorporate factors beyond assists to more accurately capture player relationships.
Improve accuracy
- Enhance AUC through better training methods and expanded datasets.
Integrate natural language processing
- Analyze player interviews and social media posts to add new perspectives.
Write English articles
- Publish content in English to reach a broader international audience.
Develop a GUI for graph visualization
- Create a web application to allow users to explore player chemistry interactively.

Conclusion

In this post, I introduced my attempt to predict NBA player chemistry.

Although the model is still a work in progress, I hope to achieve even more interesting results with further improvements.

I’d love to hear your thoughts and advice in the comments!

Let me know if you’d like further refinements!

DEV Community: sea-turt1e

Building an MCP Server Using My Custom Python Library

Introduction

What is MCP?

What I Created

Technical Stack

Project Structure

Key Implementation Points

1. Basic MCP Server Architecture

2. Flexible Configuration Options

3. Environment Standardization via Docker

Main Dockerfile (uv version)

Fallback Dockerfile (pip version)

4. Convenient Helper Script

Configuration for Claude Desktop

Local Execution Version

Docker Version

Development Challenges

1. Rust Dependency Issues

2. Choosing Between uv and pip

Practical Usage Examples

Conclusion

【kanjiconv】A Python Conversion Library for Converting "Kanji" to "Kana/Romanized" Text, Supporting Proper Nouns

Introduction

GitHub Repositry

Installation

Installing kanjiconv

Usage

Import and Instance Generation

Convert Kanji to Hiragana

Convert Kanji to Katakana

Convert Kanji to Romanized Text

Change the Separator

Conclusion

License

[Sample Code] Using Amazon Bedrock Claude's ToolUse with AWS SDK for Go v2

AWS SDK for Go v2

What is ToolUse?

Code

Full Code

Code Explanation

Setting Environment Variables

Loading Environment Variables

Defining Tool Name and Input Schema

Setting System Instructions and User Message

Defining Tool Configuration

Request to Claude

Handling the Response

Conclusion

Predicting NBA Player Chemistry Using Graph Neural Networks

Overview

Caution: About NBA

chemistry Prediction Results

explanation of edge and score

chemistry Prediction for Star Players

chemistry Predictions for Major Trades in the 2022–23 Season

Technical Details

What is a GNN?

What is AUC?

Learning Curve and AUC Progression

Dataset

Code Details

Future Prospects

Conclusion

2. Choosing Between `uv` and `pip`