{"id":36420533,"url":"https://github.com/thought2code/mcp-annotated-java-sdk","last_synced_at":"2026-04-24T12:02:30.219Z","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-03-28T03:02:56.000Z","size":838,"stargazers_count":27,"open_issues_count":3,"forks_count":11,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-28T08:51:01.812Z","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","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-03-28T03:48:47.000Z","dependencies_parsed_at":"2026-03-28T05:04:24.710Z","dependency_job_id":null,"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":21,"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":32222483,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T10:26:35.452Z","status":"ssl_error","status_checked_at":"2026-04-24T10:25:27.643Z","response_time":64,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-04-24T12:02:30.213Z","avatar_url":"https://github.com/thought2code.png","language":"Java","funding_links":[],"categories":["人工智能"],"sub_categories":["Spring Cloud框架"],"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://central.sonatype.com/artifact/io.github.thought2code/mcp-annotated-java-sdk)\n[![Commit Activity](https://img.shields.io/github/commit-activity/w/thought2code/mcp-annotated-java-sdk)](https://github.com/thought2code/mcp-annotated-java-sdk/graphs/commit-activity)\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\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 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\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.13.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n**Gradle:**\n```gradle\nimplementation 'io.github.thought2code:mcp-annotated-java-sdk:0.13.0'\n```\n\n#### Step 2: Create Configuration File\n\nCreate `mcp-server.yml` in your `src/main/resources`:\n\n```yaml\nenabled: true\nmode: STDIO\nname: my-first-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\n```\n\n#### Step 3: Create Your MCP Server\n\n```java\n@McpServerApplication\npublic class MyFirstMcpServer {\n    public static void main(String[] args) {\n        McpApplication.run(MyFirstMcpServer.class, args);\n    }\n}\n```\n\n#### Step 4: 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 5: 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\") int a,\n        @McpToolParam(name = \"b\", description = \"Second number\") int b\n    ) {\n        return a + b;\n    }\n}\n```\n\n#### Step 6: 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\") String language,\n        @McpPromptParam(name = \"task\", description = \"Task description\") String task\n    ) {\n        return String.format(\"Write %s code to: %s\", language, task);\n    }\n}\n```\n\n#### Step 7: Run Your Server\n\n```bash\n# Compile and run\n./mvnw 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\n| Mode           | Description                         | Use Case                                     |\n|----------------|-------------------------------------|----------------------------------------------|\n| **STDIO**      | Standard input/output communication | CLI tools, local development                 |\n| **SSE**        | Server-Sent Events (HTTP-based)     | Real-time web applications (deprecated)      |\n| **STREAMABLE** | HTTP streaming                      | Web applications, recommended for production |\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\n### Configuration Properties\n\n| Property              | Description                               | Default      |\n|-----------------------|-------------------------------------------|--------------|\n| `enabled`             | Enable/disable MCP server                 | `true`       |\n| `mode`                | Server mode: `STDIO`, `SSE`, `STREAMABLE` | `STREAMABLE` |\n| `name`                | Server name                               | `mcp-server` |\n| `version`             | Server version                            | `1.0.0`      |\n| `type`                | Server type: `SYNC`, `ASYNC`              | `SYNC`       |\n| `request-timeout`     | Request timeout in milliseconds           | `20000`      |\n| `capabilities`        | Enable resources, prompts, tools          | all `true`   |\n| `change-notification` | Enable change notifications               | all `true`   |\n\n### Profile-based Configuration\n\nYou can use profiles for different environments:\n\n```yaml\n# mcp-server.yml (base configuration)\nenabled: true\nmode: STREAMABLE\nname: my-mcp-server\nversion: 1.0.0\nprofile: dev\n```\n\n```yaml\n# mcp-server-dev.yml (profile-specific configuration)\nstreamable:\n  port: 8080\n```\n\n### Multilingual Support (i18n)\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        McpApplication.run(I18nMcpServer.class, args);\n    }\n}\n```\n\nCreate resource bundles:\n\n```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\n```properties\n# messages_zh_CN.properties\ntool.calculate.description=计算两个数字的和\ntool.calculate.param.a.description=第一个数字\ntool.calculate.param.b.description=第二个数字\n```\n\nUse i18n keys in your MCP components:\n\n```java\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\n./mvnw clean test\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: What Maven version is required?\n\n**A:** Just use the provided Maven wrapper script `./mvnw` to build this project.\n\n### Q: How do I debug my MCP server?\n\n**A:** You can use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) and set Java breakpoints to debug your MCP server.\n\n### Q: Which server mode should I use?\n\n**A:** \n- **STDIO**: For CLI tools and local development\n- **STREAMABLE**: For web applications and production deployments (recommended)\n- **SSE**: Deprecated, use STREAMABLE instead\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. **Add tests** for your changes\n4. **Update documentation** if necessary\n5. **Ensure all tests pass**\n6. **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\n./mvnw clean install\n\n# Run tests\n./mvnw clean 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","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"}