{"id":36420533,"url":"https://github.com/thought2code/mcp-annotated-java-sdk","last_synced_at":"2026-01-17T00:39:45.830Z","repository":{"id":286147406,"uuid":"960300383","full_name":"thought2code/mcp-annotated-java-sdk","owner":"thought2code","description":"Annotation-driven MCP dev 🚀 No Spring, Zero Boilerplate, Pure Java","archived":false,"fork":false,"pushed_at":"2026-01-11T14:57:12.000Z","size":717,"stargazers_count":23,"open_issues_count":2,"forks_count":8,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-11T19:07:13.064Z","etag":null,"topics":["ai-agents","annotation-driven","declarative","java","mcp","mcp-server","model-context-protocol","no-spring","sdk"],"latest_commit_sha":null,"homepage":"https://thought2code.github.io/mcp-annotated-java-sdk-docs","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thought2code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-04T07:40:24.000Z","updated_at":"2026-01-09T11:34:15.000Z","dependencies_parsed_at":"2025-05-18T07:32:03.668Z","dependency_job_id":"5eecaa5d-0097-40b2-8d8a-855d2e4aec18","html_url":"https://github.com/thought2code/mcp-annotated-java-sdk","commit_stats":null,"previous_names":["codeboyzhou/mcp-declarative-java-sdk","thought2code/mcp-annotated-java-sdk"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/thought2code/mcp-annotated-java-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thought2code%2Fmcp-annotated-java-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thought2code%2Fmcp-annotated-java-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thought2code%2Fmcp-annotated-java-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thought2code%2Fmcp-annotated-java-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thought2code","download_url":"https://codeload.github.com/thought2code/mcp-annotated-java-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thought2code%2Fmcp-annotated-java-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28408711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","annotation-driven","declarative","java","mcp","mcp-server","model-context-protocol","no-spring","sdk"],"created_at":"2026-01-11T17:32:47.988Z","updated_at":"2026-01-14T02:19:05.728Z","avatar_url":"https://github.com/thought2code.png","language":"Java","readme":"# Annotation-driven MCP Java SDK\n\n![Java](https://img.shields.io/badge/Java-17+-blue)\n[![maven-central](https://img.shields.io/maven-central/v/io.github.thought2code/mcp-annotated-java-sdk?color=blue)](https://mvnrepository.com/artifact/io.github.thought2code/mcp-annotated-java-sdk)\n[![coverage](https://img.shields.io/codecov/c/github/thought2code/mcp-annotated-java-sdk?logo=codecov\u0026color=brightgreen)](https://app.codecov.io/github/thought2code/mcp-annotated-java-sdk)\n[![GitHub Action](https://github.com/thought2code/mcp-annotated-java-sdk/actions/workflows/maven-build.yml/badge.svg)](https://github.com/thought2code/mcp-annotated-java-sdk/actions/workflows/maven-build.yml)\n[![License](https://img.shields.io/github/license/thought2code/mcp-annotated-java-sdk)](LICENSE)\n\n\u003e Annotation-driven MCP dev 🚀 No Spring, Zero Boilerplate, Pure Java.\n\nThis SDK is a lightweight, annotation-based framework that simplifies MCP server development in Java. Define, develop and integrate your MCP Resources / Prompts / Tools with minimal code - No Spring Framework Required.\n\n[📖 Documentation](https://thought2code.github.io/mcp-annotated-java-sdk-docs) | [💡 Examples](https://github.com/thought2code/mcp-java-sdk-examples/tree/main/mcp-server-filesystem/mcp-server-filesystem-annotated-sdk-implementation) | [🐛 Report Issues](https://github.com/thought2code/mcp-annotated-java-sdk/issues)\n\n## ✨ Why Choose This SDK?\n\n### Key Advantages\n\n- 🚫 **No Spring Framework Required** - Pure Java, lightweight and fast\n- ⚡ **Instant MCP Server** - Get your server running with just 1 line of code\n- 🎉 **Zero Boilerplate** - No need to write low-level MCP SDK code\n- 👏 **No JSON Schema** - Forget about complex and lengthy JSON definitions\n- 🎯 **Focus on Logic** - Concentrate on your core business logic\n- 🔌 **Spring AI Compatible** - Configuration file compatible with Spring AI Framework\n- 🌍 **Multilingual Support** - Built-in i18n support for MCP components\n- 📦 **Type-Safe** - Leverage Java's type system for compile-time safety\n\n### Comparison with [Official MCP Java SDK](https://github.com/modelcontextprotocol/java-sdk)\n\n| Feature        | Official MCP SDK | This SDK        |\n|----------------|------------------|-----------------|\n| Code Required  | ~50-100 lines    | ~5-10 lines     |\n| JSON Schema    | Hand-coded JSON  | No need to care |\n| Type Safety    | Limited          | Full            |\n| Learning Curve | Steep            | Gentle          |\n| Multilingual   | Unsupported      | Supported       |\n\n## 🎯 Quick Start\n\n### Prerequisites\n\n- **Java 17 or later** (required by official MCP Java SDK)\n- **Maven 3.6+** or **Gradle 7+**\n\n### 5-Minutes Tutorial\n\n#### Step 1: Add Dependency\n\n**Maven:**\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.thought2code\u003c/groupId\u003e\n    \u003cartifactId\u003emcp-annotated-java-sdk\u003c/artifactId\u003e\n    \u003cversion\u003e0.10.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n**Gradle:**\n```gradle\nimplementation 'io.github.thought2code:mcp-annotated-java-sdk:0.10.0'\n```\n\n#### Step 2: Create Your First MCP Server\n\n```java\n@McpServerApplication\n// If your MCP server components don't need to be multilingual, you can remove this annotation.\n@McpI18nEnabled(resourceBundleBaseName = \"i18n/mcp_server_components_info\")\npublic class MyFirstMcpServer {\n    public static void main(String[] args) {\n        McpServers.run(MyFirstMcpServer.class, args)\n            .startStdioServer(McpServerInfo.builder()\n                .name(\"my-first-mcp-server\")\n                .version(\"1.0.0\")\n                .build());\n    }\n}\n```\n\n#### Step 3: Define MCP Resources (if needed)\n\n```java\npublic class MyResources {\n    @McpResource(uri = \"system://info\", description = \"System information\")\n    public Map\u003cString, String\u003e getSystemInfo() {\n        Map\u003cString, String\u003e info = new HashMap\u003c\u003e();\n        info.put(\"os\", System.getProperty(\"os.name\"));\n        info.put(\"java\", System.getProperty(\"java.version\"));\n        info.put(\"cores\", String.valueOf(Runtime.getRuntime().availableProcessors()));\n        return info;\n    }\n}\n```\n\n#### Step 4: Define MCP Tools\n\n```java\npublic class MyTools {\n    @McpTool(description = \"Calculate the sum of two numbers\")\n    public int add(\n        @McpToolParam(name = \"a\", description = \"First number\", required = true) int a,\n        @McpToolParam(name = \"b\", description = \"Second number\", required = true) int b\n    ) {\n        return a + b;\n    }\n}\n```\n\n#### Step 5: Define MCP Prompts (if needed)\n\n```java\npublic class MyPrompts {\n    @McpPrompt(description = \"Generate code for a given task\")\n    public String generateCode(\n        @McpPromptParam(name = \"language\", description = \"Programming language\", required = true) String language,\n        @McpPromptParam(name = \"task\", description = \"Task description\", required = true) String task\n    ) {\n        return String.format(\"Write %s code to: %s\", language, task);\n    }\n}\n```\n\n#### Step 6: Run Your Server\n\n```bash\n# Compile and run\nmvn clean package\njava -jar target/your-app.jar\n```\n\nThat's it! Your MCP server is now ready to serve resources, tools, and prompts!\n\n## 📚 Core Concepts\n\n### What is MCP?\n\nThe [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is a standardized protocol for building servers that expose data and functionality to LLM applications. Think of it like a web API, but specifically designed for LLM interactions.\n\n### MCP Components\n\n| Component     | Purpose            | Analogy        |\n|---------------|--------------------|----------------|\n| **Resources** | Expose data to LLM | GET endpoints  |\n| **Tools**     | Execute actions    | POST endpoints |\n| **Prompts**   | Reusable templates | Form templates |\n\n### Supported Server Modes\n\nThis SDK supports three MCP server modes:\n\n1. **STDIO** - Standard input/output communication (default for CLI tools)\n2. **SSE (Server-Sent Events)** - HTTP-based real-time communication\n3. **Streamable HTTP** - HTTP streaming for web applications\n\n## 🔧 Advanced Usage\n\n### Configuration File\n\nCreate `mcp-server.yml` in your classpath:\n\n```yaml\nenabled: true\nmode: STREAMABLE\nname: my-mcp-server\nversion: 1.0.0\ntype: SYNC\nrequest-timeout: 20000\ncapabilities:\n  resource: true\n  prompt: true\n  tool: true\nchange-notification:\n  resource: true\n  prompt: true\n  tool: true\nstreamable:\n  mcp-endpoint: /mcp/message\n  disallow-delete: true\n  keep-alive-interval: 30000\n  port: 8080\n```\n\nThen start your server:\n\n```java\nMcpServers servers = McpServers.run(MyMcpServer.class, args);\nservers.startServer();  // Uses default mcp-server.yml\n// or\nservers.startServer(\"custom-config.yml\");\n```\n\n### Multilingual Support\n\nEnable i18n for your MCP components:\n\n```java\n@McpServerApplication\n@McpI18nEnabled(resourceBundleBaseName = \"messages\")\npublic class I18nMcpServer {\n    public static void main(String[] args) {\n        McpServers.run(I18nMcpServer.class, args)\n            .startStdioServer(McpServerInfo.builder()\n                .name(\"i18n-server\")\n                .version(\"1.0.0\")\n                .build());\n    }\n}\n\n// Create messages.properties\n# messages.properties\ntool.calculate.description=Calculate the sum of two numbers\ntool.calculate.param.a.description=First number\ntool.calculate.param.b.description=Second number\n\n// Create messages_zh_CN.properties\n# messages_zh_CN.properties\ntool.calculate.description=计算两个数字的和\ntool.calculate.param.a.description=第一个数字\ntool.calculate.param.b.description=第二个数字\n\n// Then use the i18n messages in your MCP components, like this:\n@McpTool(description = \"tool.calculate.description\")\npublic int add(\n    @McpToolParam(name = \"a\", description = \"tool.calculate.param.a.description\") int a,\n    @McpToolParam(name = \"b\", description = \"tool.calculate.param.b.description\") int b\n) {\n    return a + b;\n}\n```\n\n## 🏗️ Project Structure\n\nA typical project structure:\n\n```\nyour-mcp-project/\n├── pom.xml\n├── src/\n│   ├── main/\n│   │   ├── java/\n│   │   │   └── com/\n│   │   │       └── example/\n│   │   │           ├── MyMcpServer.java          # Main entry point\n│   │   │           ├── components/\n│   │   │           │   ├── MyResources.java     # MCP Resources\n│   │   │           │   ├── MyTools.java         # MCP Tools\n│   │   │           │   └── MyPrompts.java       # MCP Prompts\n│   │   │           └── service/\n│   │   │               └── BusinessLogic.java    # Your business logic\n│   │   └── resources/\n│   │       ├── mcp-server.yml                    # MCP configuration\n│   │       └── messages.properties               # i18n messages\n│   └── test/\n│       └── java/\n│           └── com/\n│               └── example/\n│                   └── McpServerTest.java         # Unit tests\n```\n\n## 🧪 Testing\n\nRun the test suite:\n\n```bash\nmvn test\n```\n\nRun tests with coverage:\n\n```bash\nmvn clean test jacoco:report\n```\n\n## ❓ FAQ\n\n### Q: Do I need Spring Framework?\n\n**A:** No! This SDK is completely independent of Spring Framework. However, the configuration file format is compatible with Spring AI if you want to migrate.\n\n### Q: Can I use this in production?\n\n**A:** This project is currently in active development. While it's stable for development and testing, we recommend thorough testing before production use.\n\n### Q: What Java version is required?\n\n**A:** Java 17 or later is required, as this is a constraint of the underlying MCP Java SDK.\n\n### Q: How do I debug my MCP server?\n\n**A:** You can use the [inspector](https://github.com/modelcontextprotocol/inspector) and set Java breakpoint to debug your MCP server.\n\n## 🤝 Contributing\n\nWe welcome and appreciate contributions! Please follow these steps to contribute:\n\n1. **Fork the repository**\n2. **Create a new branch** for your feature or bug fix\n3. **Submit a pull request** with a clear description of your changes\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/thought2code/mcp-annotated-java-sdk.git\ncd mcp-annotated-java-sdk\n\n# Build the project\nmvn clean install\n\n# Run tests\nmvn test\n```\n\n## 📖 Documentation\n\n- [Official Documentation](https://thought2code.github.io/mcp-annotated-java-sdk-docs)\n- [Examples Repository](https://github.com/thought2code/mcp-java-sdk-examples/tree/main/mcp-server-filesystem/mcp-server-filesystem-annotated-sdk-implementation)\n- [MCP Official Site](https://modelcontextprotocol.io)\n\n## 📄 License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n## 🙏 Acknowledgments\n\n- [MCP Java SDK](https://github.com/modelcontextprotocol/java-sdk) - The underlying MCP implementation\n- [Model Context Protocol](https://modelcontextprotocol.io) - The protocol specification\n\n\u003e [!NOTE]\n\u003e This project is under active development. We appreciate your feedback and contributions!\n","funding_links":[],"categories":["人工智能"],"sub_categories":["Spring Cloud框架"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthought2code%2Fmcp-annotated-java-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthought2code%2Fmcp-annotated-java-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthought2code%2Fmcp-annotated-java-sdk/lists"}