Skip to content

Commit c44d4a3

Browse files
shopewfshopewf
authored
[CHORE] Update readme for PyPi packages (#32)
Signed-off-by: will.shope <[email protected]>
1 parent 7c4ad32 commit c44d4a3

File tree

1 file changed

+88
-48
lines changed

1 file changed

+88
-48
lines changed

‎README.md‎

Lines changed: 88 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) 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. If you are using OCI servers, configure your [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,10 @@ 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
70+
71+
Some MCP servers may not work with token-based authentication alone. See more about API key-based authentication [here](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/clitoken.htm).
7772

7873
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.
7974

@@ -82,6 +77,8 @@ Remember to refresh the session once it expires with:
8277
oci session authenticate --profile-name <profile_name> --region <region> --auth security_token
8378
```
8479

80+
`<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.
81+
8582
## Client configuration
8683

8784
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 +90,24 @@ Refer to the sections below for client-specific configuration instructions.
9390
<details>
9491
<summary>Setup</summary>
9592

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

9895
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).
9996
2. Once installed, click the extension to open it.
10097
3. Click the **MCP Servers** button near the top of the the extension's panel.
10198
4. Select the **Installed** tab.
10299
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.
100+
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.
104101

105-
For macOS/Linux
102+
For macOS/Linux:
106103
```json
107104
{
108105
"mcpServers": {
109106
"oracle-oci-api-mcp-server": {
110107
"type": "stdio",
111-
"command": "uv",
108+
"command": "uvx",
112109
"args": [
113-
"run",
114-
"oracle.oci-api-mcp-server"
110+
"oracle.oci-api-mcp-server@latest"
115111
],
116112
"env": {
117113
"OCI_CONFIG_PROFILE": "<profile_name>",
@@ -134,7 +130,7 @@ For Windows - **TODO**
134130
<details>
135131
<summary>Setup</summary>
136132

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

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

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

147143
For macOS/Linux:
148-
149144
```json
150145
{
151146
"mcpServers": {
152147
"oracle-oci-api-mcp-server": {
153148
"type": "stdio",
154-
"command": "uv",
149+
"command": "uvx",
155150
"args": [
156-
"run",
157151
"oracle.oci-api-mcp-server"
158152
],
159153
"env": {
@@ -165,6 +159,8 @@ For macOS/Linux:
165159
}
166160
```
167161

162+
`<profile_name>` is the profile that you set up during the [authentication](#authentication) steps.
163+
168164
For Windows - **TODO**
169165

170166
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 +172,7 @@ For Windows - **TODO**
176172
<details>
177173
<summary>Setup</summary>
178174

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

181177
1. Download [Ollama](https://ollama.com/download)
182178
2. Start the Ollama server
@@ -195,27 +191,27 @@ For Linux: `sudo systemctl start ollama`
195191
8. Create an mcphost configuration file (e.g. `./mcphost.json`)
196192
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.
197193

198-
For macOS/Linux
199-
194+
For macOS/Linux:
200195
```json
201196
{
202197
"mcpServers": {
203198
"oracle-oci-api-mcp-server": {
204199
"type": "stdio",
205-
"command": "uv",
200+
"command": "uvx",
206201
"args": [
207-
"run",
208202
"oracle.oci-api-mcp-server"
209203
],
210204
"env": {
211-
"VIRTUAL_ENV": "<path to your cloned repo>/oci-mcp/.venv",
205+
"OCI_CONFIG_PROFILE": "<profile_name>",
212206
"FASTMCP_LOG_LEVEL": "ERROR"
213207
}
214208
}
215209
}
216210
}
217211
```
218212

213+
`<profile_name>` is the profile that you set up during the [authentication](#authentication) steps.
214+
219215
For Windows - **TODO**
220216

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

226222
</details>
227223

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

0 commit comments

Comments
 (0)