Skip to content

Commit b2dacda

Browse files
cobachcobach
committed
feat: Initial release of MCP Java Bridge
Runtime decoupling solution for MCP Java servers that solves tight coupling issues in stdio-based integration. Provides transparent TCP transport while maintaining full stdio compatibility with MCP clients. Features: - Decouples client and server runtimes to prevent resource conflicts - Transparent TCP transport with stdio compatibility - Automatic SDK version detection and runtime fixes for 0.10.0 - Zero code changes required for existing MCP servers - Comprehensive demo application with multiple tools - Production-ready with logging and error handling 🤖 Generated with Claude Wing Coding support (https://claude.ai)
0 parents  commit b2dacda

39 files changed

Lines changed: 4028 additions & 0 deletions

‎.gitignore‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Gradle
2+
.gradle/
3+
build/
4+
!gradle/wrapper/gradle-wrapper.jar
5+
!**/src/main/**/build/
6+
!**/src/test/**/build/
7+
8+
# IDE
9+
.idea/
10+
*.iml
11+
*.ipr
12+
*.iws
13+
.vscode/
14+
.settings/
15+
.project
16+
.classpath
17+
18+
# OS
19+
.DS_Store
20+
Thumbs.db
21+
22+
# Logs
23+
*.log
24+
logs/
25+
26+
# Local configuration
27+
local.properties

‎CHANGELOG.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Changelog
2+
3+
All notable changes to MCP Java Bridge will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
- Initial implementation of TCP transport bridge for MCP Java SDK
12+
- BridgeTransportProvider for TCP server socket management
13+
- BridgeTransport for stdio↔TCP protocol conversion
14+
- BridgeStub client for Claude Desktop compatibility
15+
- Static factory methods in McpBridge for easy configuration
16+
- Builder pattern support for advanced configuration
17+
- LoggingUtils for file-based debug logging
18+
- JsonSchemaUtils for parameter schema generation
19+
- Example implementations (SimpleExample, ExampleServer)
20+
- Comprehensive documentation and API reference
21+
22+
### Technical Details
23+
- Compatible with MCP Java SDK 0.11.0-SNAPSHOT
24+
- Implements MCP transport protocol specification
25+
- Thread-safe message handling with synchronized writes
26+
- Reactive programming with Project Reactor
27+
- Automatic JSON-RPC message serialization/deserialization
28+
- Connection pooling with dedicated threads per client
29+
- Graceful shutdown and error recovery
30+
31+
## [1.0.0] - TBD
32+
33+
### Notes
34+
- First stable release
35+
- Production-ready TCP transport support
36+
- Full compatibility with Claude Desktop app
37+
- Comprehensive test coverage
38+
39+
---
40+
41+
## Version History Format
42+
43+
### [Version] - YYYY-MM-DD
44+
45+
#### Added
46+
- New features
47+
48+
#### Changed
49+
- Changes in existing functionality
50+
51+
#### Deprecated
52+
- Soon-to-be removed features
53+
54+
#### Removed
55+
- Removed features
56+
57+
#### Fixed
58+
- Bug fixes
59+
60+
#### Security
61+
- Security vulnerability fixes

‎CONTRIBUTING.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# Contributing to MCP Java Bridge
2+
3+
We welcome contributions to the MCP Java Bridge project! This document provides guidelines for contributing to the project.
4+
5+
## Development Setup
6+
7+
### Prerequisites
8+
9+
- Java 17 or higher
10+
- Gradle 8.5 or higher
11+
- Git
12+
13+
### Getting Started
14+
15+
1. Fork the repository
16+
2. Clone your fork:
17+
```bash
18+
git clone https://github.com/YOUR_USERNAME/mcp-java-bridge.git
19+
cd mcp-java-bridge
20+
```
21+
22+
3. Build the project:
23+
```bash
24+
./gradlew build
25+
```
26+
27+
4. Run tests:
28+
```bash
29+
./gradlew test
30+
```
31+
32+
## Development Workflow
33+
34+
### 1. Create a Feature Branch
35+
36+
```bash
37+
git checkout -b feature/your-feature-name
38+
```
39+
40+
### 2. Make Your Changes
41+
42+
- Follow the existing code style
43+
- Add tests for new functionality
44+
- Update documentation as needed
45+
46+
### 3. Run Tests
47+
48+
```bash
49+
./gradlew test
50+
```
51+
52+
### 4. Commit Your Changes
53+
54+
Follow the conventional commit format:
55+
56+
```
57+
<type>: <description>
58+
59+
<detailed explanation if needed>
60+
61+
🤖 Generated with Claude Wing Coding support (https://claude.ai)
62+
```
63+
64+
Types:
65+
- `feat`: New feature
66+
- `fix`: Bug fix
67+
- `docs`: Documentation changes
68+
- `style`: Code style changes
69+
- `refactor`: Code refactoring
70+
- `test`: Adding or updating tests
71+
- `chore`: Maintenance tasks
72+
73+
### 5. Push and Create Pull Request
74+
75+
```bash
76+
git push origin feature/your-feature-name
77+
```
78+
79+
Then create a pull request on GitHub.
80+
81+
## Code Style Guidelines
82+
83+
### Java Code
84+
85+
- Use 4 spaces for indentation
86+
- Follow standard Java naming conventions
87+
- Use Lombok annotations where appropriate
88+
- Add Javadoc for public APIs
89+
90+
### Package Structure
91+
92+
```
93+
org.gegolabs.mcp.bridge
94+
├── transport/ # Transport implementations
95+
├── client/ # Client-side components
96+
├── utils/ # Utility classes
97+
└── examples/ # Example implementations
98+
```
99+
100+
### Logging
101+
102+
- Use SLF4J with `@Slf4j` annotation
103+
- Log levels:
104+
- ERROR: Unrecoverable errors
105+
- WARN: Recoverable errors, deprecations
106+
- INFO: Important state changes
107+
- DEBUG: Detailed flow information
108+
- TRACE: Very detailed debugging
109+
110+
## Testing Guidelines
111+
112+
### Unit Tests
113+
114+
- Test class naming: `<ClassName>Test`
115+
- Use JUnit 5 (Jupiter)
116+
- Use Mockito for mocking
117+
- Aim for >80% code coverage
118+
119+
Example:
120+
```java
121+
@Test
122+
void testTcpTransportCreation() {
123+
var transport = McpBridge.tcpTransport(3000);
124+
assertNotNull(transport);
125+
assertInstanceOf(BridgeTransportProvider.class, transport);
126+
}
127+
```
128+
129+
### Integration Tests
130+
131+
- Test actual TCP connections
132+
- Test stdio↔TCP conversion
133+
- Test error scenarios
134+
135+
## Documentation
136+
137+
### Code Documentation
138+
139+
- Add Javadoc to all public classes and methods
140+
- Include examples in Javadoc where helpful
141+
- Document thrown exceptions
142+
143+
### README Updates
144+
145+
Update README.md when:
146+
- Adding new features
147+
- Changing API
148+
- Adding configuration options
149+
150+
### API Documentation
151+
152+
Update docs/API.md when:
153+
- Adding new public APIs
154+
- Changing method signatures
155+
- Adding new utility classes
156+
157+
## Pull Request Process
158+
159+
1. **Description**: Clearly describe what the PR does
160+
2. **Testing**: Describe how you tested the changes
161+
3. **Breaking Changes**: Note any breaking changes
162+
4. **Related Issues**: Link related issues with "Fixes #123"
163+
164+
### PR Template
165+
166+
```markdown
167+
## Description
168+
Brief description of changes
169+
170+
## Problem
171+
What issue does this solve?
172+
173+
## Solution
174+
How does this solve it?
175+
176+
## Testing
177+
- [ ] Unit tests pass
178+
- [ ] Integration tests pass
179+
- [ ] Manual testing completed
180+
181+
## Type of Change
182+
- [ ] Bug fix
183+
- [ ] New feature
184+
- [ ] Breaking change
185+
- [ ] Documentation update
186+
```
187+
188+
## Release Process
189+
190+
1. Update version in `build.gradle`
191+
2. Update CHANGELOG.md
192+
3. Create release tag: `v1.0.0`
193+
4. Build and publish artifacts
194+
195+
## Getting Help
196+
197+
- Open an issue for bugs
198+
- Start a discussion for features
199+
- Join our community chat (if available)
200+
201+
## Code of Conduct
202+
203+
- Be respectful and inclusive
204+
- Welcome newcomers
205+
- Focus on constructive criticism
206+
- Follow the project's code of conduct
207+
208+
Thank you for contributing to MCP Java Bridge!

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 GegoLabs
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

0 commit comments

Comments
 (0)