Skip to content

Commit 4b15835

Browse files
shopewfshopewf
committed
[CHORE] Update readme for PyPi packages
Signed-off-by: will.shope <[email protected]>
1 parent c92a0ab commit 4b15835

File tree

1 file changed

+86
-48
lines changed

1 file changed

+86
-48
lines changed

‎README.md‎

Lines changed: 86 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -27,40 +27,33 @@ Always see the respective `src/<server>/README.md` for detailed setup instructio
2727

2828
## Quick Start
2929

30-
1. **Clone this repository:**
31-
```sh
32-
git clone https://github.com/oracle/mcp.git
33-
cd mcp
34-
```
30+
Follow these instructions to get started as quickly as possible. Once finished, look [here](#local-development) to set up your local development environment if you wish to [contribute](#contributing) code changes.
3531

36-
2. **List available MCP servers:**
37-
```sh
38-
ls src/
39-
```
32+
1. Install `uv` from [here](https://docs.astral.sh/uv/getting-started/installation/)
33+
2. Install python with `uv python install 3.13`
34+
3. Configure [OCI authentication](#authentication)
35+
4. Add desired servers to your [MCP client configuration](#client-configuration)
4036

41-
3. **Read the appropriate server's README for setup instructions:**
42-
```sh
43-
cat src/<server-name>/README.md
44-
```
45-
- Example: For the Python-based DBTools MCP server:
46-
```
47-
cd src/dbtools-mcp-server/
48-
cat README.md
49-
```
37+
Below is an example MCP client configuration for a typical python server
5038

51-
4. **Typical Python Server Setup Example:**
52-
```sh
53-
python3 -m venv venv
54-
source venv/bin/activate # On Windows: venv\Scripts\activate
55-
pip install -r requirements-dev.txt
56-
```
57-
*(For Node.js/Java/other servers, follow respective instructions in that server’s README)*
39+
*(For Node.js/Java/other servers, follow respective instructions in that server’s README)*
5840

59-
5. **Build and Install servers in the current virtual environment**
60-
```sh
61-
make build
62-
make install
63-
```
41+
For macOS/Linux:
42+
```
43+
{
44+
"mcpServers": {
45+
"oracle-oci-api-mcp-server": {
46+
"command": "uvx",
47+
"args": [
48+
"oracle.oci-api-mcp-server@latest"
49+
],
50+
"env": {
51+
"FASTMCP_LOG_LEVEL": "ERROR"
52+
}
53+
}
54+
}
55+
}
56+
```
6457

6558
## Authentication
6659

@@ -72,8 +65,8 @@ For OCI MCP servers, you'll need to install and authenticate using the OCI CLI.
7265
oci session authenticate --region=<region> --tenancy-name=<tenancy_name>
7366
```
7467
where:
75-
<region> is the region you would like to authenticate in (e.g. `us-phoenix-1`)
76-
<tenancy_name> is the name of your OCI tenancy
68+
`<region>` is the region you would like to authenticate in (e.g. `us-phoenix-1`)
69+
`<tenancy_name>` is the name of your OCI tenancy
7770

7871
All actions are performed with the permissions of the configured OCI CLI profile. We advise least-privilege IAM setup, secure credential management, safe network practices, secure logging, and warn against exposing secrets.
7972

@@ -82,6 +75,8 @@ Remember to refresh the session once it expires with:
8275
oci session authenticate --profile-name <profile_name> --region <region> --auth security_token
8376
```
8477

78+
`<profile_name>` is the profile that you set up in the steps above. You can view a list of your profiles by running `cat ~/.oci/config` on macOS/Linux if you forget which profile you have set up.
79+
8580
## Client configuration
8681

8782
Each MCP server exposes endpoints that your client can connect to. To enable this connection, just add the relevant server to your MCP client’s configuration file. You can find the list of servers under the `src` folder.
@@ -93,25 +88,24 @@ Refer to the sections below for client-specific configuration instructions.
9388
<details>
9489
<summary>Setup</summary>
9590

96-
Before continuing, make sure you have already followed the steps above in the [Getting Started](#getting-started) section.
91+
Before continuing, make sure you have already followed the steps above in the [Quick start](#quick-start) section.
9792

9893
1. If using Visual Studio Code, install the [Cline VS Code Extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev) (or equivalent extension for your preferred IDE).
9994
2. Once installed, click the extension to open it.
10095
3. Click the **MCP Servers** button near the top of the the extension's panel.
10196
4. Select the **Installed** tab.
10297
5. Click **Configure MCP Servers** to open the `cline_mcp_settings.json` file.
103-
6. In the `cline_mcp_settings.json` file, add your desired MCP servers in the `mcpServers` object. Below is an example for for the compute OCI MCP server. Make sure to save the file after editing.
98+
6. In the `cline_mcp_settings.json` file, add your desired MCP servers in the `mcpServers` object. Below is an example for for the generic OCI API MCP server. Make sure to save the file after editing. `<profile_name>` is the profile that you set up during the [authentication](#authentication) steps.
10499

105-
For macOS/Linux
100+
For macOS/Linux:
106101
```json
107102
{
108103
"mcpServers": {
109104
"oracle-oci-api-mcp-server": {
110105
"type": "stdio",
111-
"command": "uv",
106+
"command": "uvx",
112107
"args": [
113-
"run",
114-
"oracle.oci-api-mcp-server"
108+
"oracle.oci-api-mcp-server@latest"
115109
],
116110
"env": {
117111
"OCI_CONFIG_PROFILE": "<profile_name>",
@@ -134,7 +128,7 @@ For Windows - **TODO**
134128
<details>
135129
<summary>Setup</summary>
136130

137-
Before continuing, make sure you have already followed the steps above in the [Getting Started](#getting-started) section.
131+
Before continuing, make sure you have already followed the steps above in the [Quick start](#quick-start) section.
138132

139133
1. You can place MCP configurations in two locations, depending on your use case:
140134

@@ -145,15 +139,13 @@ Before continuing, make sure you have already followed the steps above in the [G
145139
**`.cursor/mcp.json`**
146140

147141
For macOS/Linux:
148-
149142
```json
150143
{
151144
"mcpServers": {
152145
"oracle-oci-api-mcp-server": {
153146
"type": "stdio",
154-
"command": "uv",
147+
"command": "uvx",
155148
"args": [
156-
"run",
157149
"oracle.oci-api-mcp-server"
158150
],
159151
"env": {
@@ -165,6 +157,8 @@ For macOS/Linux:
165157
}
166158
```
167159

160+
`<profile_name>` is the profile that you set up during the [authentication](#authentication) steps.
161+
168162
For Windows - **TODO**
169163

170164
2. In your **Cursor Settings**, check your **Installed Servers** under the **MCP** tab to ensure that your `.cursor/mcp.json` was properly configured.
@@ -176,7 +170,7 @@ For Windows - **TODO**
176170
<details>
177171
<summary>Setup</summary>
178172

179-
Before continuing, make sure you have already followed the steps above in the [Getting Started](#getting-started) section.
173+
Before continuing, make sure you have already followed the steps above in the [Quick start](#quick-start) section.
180174

181175
1. Download [Ollama](https://ollama.com/download)
182176
2. Start the Ollama server
@@ -195,27 +189,27 @@ For Linux: `sudo systemctl start ollama`
195189
8. Create an mcphost configuration file (e.g. `./mcphost.json`)
196190
9. Add your desired server to the `mcpServers` object. Below is an example for for the compute OCI MCP server. Make sure to save the file after editing.
197191

198-
For macOS/Linux
199-
192+
For macOS/Linux:
200193
```json
201194
{
202195
"mcpServers": {
203196
"oracle-oci-api-mcp-server": {
204197
"type": "stdio",
205-
"command": "uv",
198+
"command": "uvx",
206199
"args": [
207-
"run",
208200
"oracle.oci-api-mcp-server"
209201
],
210202
"env": {
211-
"VIRTUAL_ENV": "<path to your cloned repo>/oci-mcp/.venv",
203+
"OCI_CONFIG_PROFILE": "<profile_name>",
212204
"FASTMCP_LOG_LEVEL": "ERROR"
213205
}
214206
}
215207
}
216208
}
217209
```
218210

211+
`<profile_name>` is the profile that you set up during the [authentication](#authentication) steps.
212+
219213
For Windows - **TODO**
220214

221215
10. Start `mcphost` with `OCI_CONFIG_PROFILE=<profile> mcphost -m ollama:<model> --config <config-path>`
@@ -225,6 +219,50 @@ For Windows - **TODO**
225219

226220
</details>
227221

222+
## Local development
223+
224+
This section will help you set up your environment to prepare it for local development if you wish to [contribute](#contributing) code changes.
225+
226+
1. Set up python virtual environment and install dev requirements
227+
```sh
228+
python3 -m venv venv
229+
source venv/bin/activate # On Windows: venv\Scripts\activate
230+
pip install -r requirements-dev.txt
231+
```
232+
233+
2. Locally build and install servers within the virtual environment
234+
```sh
235+
make build
236+
make install
237+
```
238+
239+
3. Add desired servers to your MCP client configuration, but run them using the locally installed server package instead
240+
241+
Below is an example MCP client configuration for a typical python server using the local server package
242+
243+
*(For Node.js/Java/other servers, follow respective instructions in that server’s README)*
244+
245+
For macOS/Linux:
246+
```
247+
{
248+
"mcpServers": {
249+
"oracle-oci-api-mcp-server": {
250+
"command": "uv",
251+
"args": [
252+
"run"
253+
"oracle.oci-api-mcp-server"
254+
],
255+
"env": {
256+
"VIRTUAL_ENV": "<path to your cloned repo>/mcp/venv",
257+
"FASTMCP_LOG_LEVEL": "ERROR"
258+
}
259+
}
260+
}
261+
}
262+
```
263+
264+
where `<path to your cloned repo>` is the absolute path to wherever you cloned this repo that will help point to the venv created above (e.g. `/Users/myuser/dev/mcp/venv`)
265+
228266
## Directory Structure
229267
230268
```

0 commit comments

Comments
 (0)