Hugging Face's logo

Spaces:
ibm-research
/
cuga-agent
Running

App Files Community
cuga-agent
File size: 3,736 Bytes 
0646b18
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# 🚀 Quick Start Guide

Get up and running with the Tools Environment Registry in minutes!

## 1. Basic Setup

### Start with Default Configuration
```bash
# Navigate to the project root
cd <repo>

# Start the registry server with default config
uv run python -m cuga.backend.tools_env.registry.registry.api_registry_server
```

The server will start at `http://127.0.0.1:8001`

### Verify Installation
```bash
# Check server health
curl http://localhost:8001/

# List available applications
curl http://localhost:8001/applications
```

## 2. Add Your First MCP Server

### File System Server (Easiest Start)
```yaml
# config/my_first_config.yaml
mcpServers:
  my_files:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/your-username/Documents"]
    description: "My document file manager"
```

### Start with Custom Config
```bash
MCP_SERVERS_FILE=config/my_first_config.yaml uv run python -m cuga.backend.tools_env.registry.registry.api_registry_server
```

## 3. Test Your Setup

### List Your Tools
```bash
curl http://localhost:8001/applications/my_files/apis
```

### Call a File Operation
```bash
curl -X POST http://localhost:8001/functions/call \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "my_files",
    "function_name": "my_files_list_files",
    "args": {"path": "."}
  }'
```

## 4. Add More Services

### OpenAPI Service
```yaml
services:
  - my_api:
      url: "https://jsonplaceholder.typicode.com/openapi.json"
      description: "JSONPlaceholder test API"
```

### Remote MCP Server
```yaml
mcpServers:
  remote_service:
    url: "http://your-mcp-server:8000/sse"
    description: "My remote MCP server"
```

## 5. Common Commands

```bash
# Start server
uv run python -m cuga.backend.tools_env.registry.registry.api_registry_server

# Run tests
uv run pytest cuga/backend/tools_env/registry/tests/ -v

# Start with custom config
MCP_SERVERS_FILE=/path/to/config.yaml uv run python -m cuga.backend.tools_env.registry.registry.api_registry_server

# Check logs
tail -f logs/registry_server.log
```

## 6. Next Steps

- Read the full [README.md](README.md) for detailed configuration options
- Check [config/sample_complete.yaml](config/sample_complete.yaml) for advanced examples
- Explore [config/sample_filesystem.yaml](config/sample_filesystem.yaml) for file system servers
- Review [config/sample_mcp_servers.yaml](config/sample_mcp_servers.yaml) for various MCP server types

## 🆘 Troubleshooting

### Server Won't Start
- Check if port 8001 is available: `lsof -i :8001`
- Verify configuration file exists and is valid YAML
- Check logs for detailed error messages

### MCP Server Connection Failed
- Ensure the MCP server is running and accessible
- Test connectivity: `curl http://your-mcp-server:8000/health`
- Check firewall settings

### Tool Not Found
- Verify service is listed in `/applications`
- Check exact tool name format: `service_name_tool_name`
- Ensure service loaded successfully (check logs)

## 📝 Example Workflow

1. **Create config file**:
   ```yaml
   mcpServers:
     workspace:
       command: "npx"
       args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/workspace"]
       description: "My workspace files"
   ```

2. **Start server**:
   ```bash
   MCP_SERVERS_FILE=my_config.yaml uv run python -m cuga.backend.tools_env.registry.registry.api_registry_server
   ```

3. **Test connection**:
   ```bash
   curl http://localhost:8001/applications
   ```

4. **Use your tools**:
   ```bash
   curl -X POST http://localhost:8001/functions/call \
     -H "Content-Type: application/json" \
     -d '{"app_name": "workspace", "function_name": "workspace_read_file", "args": {"path": "README.md"}}'
   ```