Emircan-Kirez/mcp-server-example

MCP Server Example

This project demonstrates how to build an MCP (Model Context Protocol) Server with STDIO transport using Spring.

🛠️ Tool Services

This project includes two service classes that provide various tools accessible through the MCP Server. Each service encapsulates a specific set of tools related to either users or accounts.

👤 UserTools Service

This service contains tools related to user operations. It includes the following four tools:

• get_all_users
  Retrieves a list of all users in the system.

• get_user_by_id
  Fetches detailed information about a user by their unique ID.

• get_username_by_id
  Returns only the username of a specific user based on their ID.

• get_user_by_phone
  Finds and returns user information using their phone number.

💼 AccountTools Service

This service includes tools related to user account operations. It currently provides the following tool:

• get_accounts_by_user_id
  Retrieves all account records associated with a given user ID.

🏗️ Building the Project

To build the project without running tests, use the following command:

./mvnw clean install -DskipTests

This will compile the code and package the application as a JAR file, skipping any test executions. The output JAR file will be located in the target/ directory.

⚙️ Claude Desktop Configuration

To use this MCP server with Claude Desktop, you need to edit your claude_desktop_config.json file.

Add the following entry to your configuration:

{
  "user-mcp-server": {
    "command": "java",
    "args": [
      "-jar",
      "/absolute/path/to/target/mcp-server-example-0.0.1-SNAPSHOT.jar"
    ],
    "env": {
      "USER_SERVICE_URL": "https://jsonplaceholder.typicode.com/users"
    }
  }
}

Replace /absolute/path/to/ with the actual path to your built jar file.

📌 Sample Questions and Responses

• ❓ Question
• 🛠️ Used Tool
• 💬 Response

❓How many users do we have?

🛠️ get_all_users

💬 You have 10 users in your system.

❓ Find me the user whose phone number is 1-770-736-8031 x56442

🛠️ get_user_by_phone

💬 I found the user with phone number 1-770-736-8031 x56442:

Name: Leanne Graham
ID: 1
Username: Bret
Email:
Phone: 1-770-736-8031 x56442
Website: hildegard.org
Address: Kulas Light, Apt. 556, Gwenborough, 92998-3874

❓ Calculate the total balance for the user whose ID is 3 and give me the average balance for accounts

🛠️ get_accounts_by_user_id get_user_by_id

💬 Here are the account details for Clementine Bauch (User ID: 3):

Individual Account Balances:

• Account ID 5: $3,000.00
• Account ID 6: $2,500.00
• Account ID 7: $400.00

Total Balance Across All Accounts: $5,900.00

Average Balance Per Account: $1,966.67 (Total: $5,900 ÷ 3 accounts = $1,966.67)