Prerequisites
- GitHub account
- Python 3.10 or higher
- Git installed locally
- Osmosis AI account
Step 1: Create Repository Structure
Create the required directory structure:Step 2: Add Python Dependencies
Createpyproject.toml in the repository root:
Step 3: Set Up MCP Server
Create Server Configuration
File:mcp/server/__init__.py
mcp/server/mcp_server.py
Create Entry Point
File:mcp/main.py
Add Your First Tool
File:mcp/tools/__init__.py
mcp/tools/math.py
Step 4: Add Reward Function
File:reward_fn/compute_reward.py
Step 5: Add Reward Rubric
File:reward_rubric/reward_rubric_openai.py
Step 6: Test Locally
Install Dependencies
Test MCP Server
Start the server:Test Reward Function
1.0
Test Reward Rubric
Set your API key:Step 7: Create .gitignore
Create.gitignore to exclude sensitive and generated files:
Step 8: Push to GitHub
Initialize git and push:Step 9: Connect to Osmosis Platform
You can connect both public and private repositories to Osmosis. For private repositories, you’ll need to grant Osmosis access through GitHub OAuth or a deploy key.
- Navigate to your Osmosis workspace settings at platform.osmosis.ai/settings/workspace/git
- Click Connect Repository
- Authorize Osmosis to access your GitHub account
- Select your repository from the list
- For private repos: Grant necessary permissions when prompted
- Click Connect and wait for initial sync
Step 10: Verify Sync
After connecting, Osmosis will automatically sync your repository. Verify the sync:- Check the Git Sync dashboard to see sync status
- Navigate to MCP Tools to see your tools listed
- Go to Reward Functions to verify your reward functions
- Check Reward Rubrics for your rubric implementations
Next Steps
Add More Components
Now that you’re set up, you can add more functionality:Add More Tools
Create additional MCP tools
More Reward Functions
Build custom scoring logic
Set Up CI/CD
Create.github/workflows/test.yml:
Configure Environment Variables
For local development, create.env file:
- Go to Settings → Environment Variables
- Add your API keys securely
- Reference them in your rubric functions
Troubleshooting
Sync Not Working
- Verify folder structure matches exactly
- Check that decorators are used correctly (
@mcp.tool(),@osmosis_reward,@osmosis_rubric) - Ensure
pyproject.tomlincludes all required dependencies - Review GitHub webhook settings in repository settings
Tools Not Appearing
- Confirm
@mcp.tool()decorator is present - Check that tools are exported in
mcp/tools/__init__.py - Verify type hints are included for all parameters
- Review Osmosis sync logs for errors
API Key Issues
- For local testing, set environment variables properly
- For Osmosis platform, configure secrets in dashboard settings
- Never commit API keys to version control (use
.gitignore) - Verify API keys are valid and have proper permissions
Import Errors
- Ensure
__init__.pyfiles exist in all package directories - Check that imports use correct relative paths
- Verify all dependencies are installed:
pip install -e .
Complete Example
For a complete working example, check out:Example Repository
Explore the official Osmosis Git Sync example with all components implemented
Getting Help
Need assistance? Here are your resources:- Documentation: Review the Best Practices guide
- Examples: Study the example repository
- Support: Contact contact@osmosis.ai