|
1 | | -# Jentic SDK & MCP Plugin [Beta] |
| 1 | +# Jentic SDK & MCP Plugin [Beta]  |
2 | 2 |
|
3 | | -Jentic MCP empowers AI agent builders to discover and integrate external APIs and workflows rapidly—without writing or maintaining API-specific code. |
| 3 | +Jentic empowers AI-agent builders to discover and integrate external APIs and workflows rapidly—without writing or maintaining any API-specific code. |
4 | 4 |
|
5 | | -This repository contains the core Jentic SDK and the Jentic MCP Plugin. |
| 5 | +This mono-repo contains: |
6 | 6 |
|
7 | | -- **[Jentic SDK](#jentic-sdk):** A comprehensive Python library for discovering and executing APIs and workflows, particularly for LLM tool use. |
8 | | -- **[Jentic MCP Plugin](#jentic-mcp-plugin):** A plugin enabling agents (like Windsurf, Claude Desktop & Cursor) to discover and use Jentic capabilities via MCP. |
| 7 | +- **Jentic SDK** – a Python library for searching, loading and executing APIs / workflows, plus helpers for turning those actions into LLM tools. |
| 8 | +- **Jentic MCP Plugin** – an MCP server that exposes the same capabilities to any MCP-compatible client (Windsurf, Claude Desktop, Cursor, …). |
9 | 9 |
|
10 | | -See the respective README files for more details: |
11 | | -- [Jentic SDK README](./python/README.md) |
12 | | -- [Jentic MCP Plugin README](./mcp/README.md) |
| 10 | +See the dedicated READMEs for full details: |
13 | 11 |
|
14 | | -The Jentic SDK is backed by the data in the [Open Agentic Knowledge (OAK)](https://github.com/jentic/oak) repository. |
| 12 | +- [`python/README.md`](./python/README.md) – SDK usage & API reference |
| 13 | +- [`mcp/README.md`](./mcp/README.md) – MCP server setup & configuration |
15 | 14 |
|
| 15 | +The SDK is backed by the data in the [Jentic Public API](https://github.com/jentic/jentic-public-api) repository. |
16 | 16 |
|
17 | | -## Getting Started |
| 17 | +## Quick start |
18 | 18 |
|
19 | | -### Prerequisites |
20 | | -- **Python 3.11 or later** |
21 | | - If you're on macOS the system's default Python is 3.9; install a newer interpreter first. |
| 19 | +### 1. Install Python package |
22 | 20 |
|
23 | | -#### Option A – Homebrew |
24 | | -```sh |
25 | | -brew install python@3.11 |
26 | | -python3.11 -m pip install --upgrade pip |
27 | | -python3.11 -m pip install jentic |
| 21 | +```bash |
| 22 | +pip install jentic |
28 | 23 | ``` |
29 | | -#### Option B – uv (or other tools to create a virtual environment) |
30 | | -```sh |
31 | | -# Create a new project folder for jentic |
32 | | -mkdir my-project && cd my-project |
33 | | -# Create a local env with Python 3.11 |
34 | | -uv venv .venv --python 3.11 |
35 | | -uv pip install jentic |
36 | | -``` |
37 | | - |
38 | | -### Get Your Jentic API Key |
39 | 24 |
|
40 | | -To use any Jentic product such as the Jentic SDK or MCP Plugin, you must first obtain a Jentic API Key. The easiest way is using the Jentic CLI. You can _optionally_ include an email address for higher rate limits and for early access to new features. |
| 25 | +### 2. Obtain your Agent API Key |
41 | 26 |
|
42 | | -```sh |
43 | | -jentic register --email '<your_email>' |
44 | | -``` |
| 27 | +Visit https://jentic.com/register to create an agent and copy the key. |
45 | 28 |
|
46 | | -This will print your UUID and an export command to set it in your environment: |
47 | 29 |
|
48 | | -```sh |
49 | | -export JENTIC_UUID=<your-jentic-uuid> |
| 30 | +```bash |
| 31 | +export JENTIC_AGENT_API_KEY=<your-agent-api-key> |
50 | 32 | ``` |
51 | 33 |
|
52 | | -Alternatively, you can use curl to register and obtain your API Key: |
53 | | - |
54 | | -```sh |
55 | | -curl -X POST https://api.jentic.com/api/v1/auth/register \ |
56 | | - -H "Content-Type: application/json" \ |
57 | | - -d '{"email": "<your_email>"}' |
58 | | -``` |
59 | | - |
60 | | -### Jentic MCP Server |
61 | | - |
62 | | -The quickest way to get started is to integrate the Jentic MCP plugin with your preferred MCP client (like Windsurf, Claude Desktop or Cursor). |
| 34 | +### 3. Use the SDK |
63 | 35 |
|
64 | | -The recommended method is to run the server directly from the GitHub repository using `uvx`. |
65 | | -You will need to install `uv` first using: |
66 | | - |
67 | | -`brew install uv` or `pip install uv` |
| 36 | +```python |
| 37 | +import asyncio |
| 38 | +from jentic import Jentic, SearchRequest, LoadRequest, ExecutionRequest |
68 | 39 |
|
69 | | -Next, add the following configuration to your MCP client. |
| 40 | +async def main(): |
| 41 | + client = Jentic() |
70 | 42 |
|
71 | | -The location of the configuration file depends on the client you are using and your OS. Some common examples: |
| 43 | + # 1️⃣ find a capability |
| 44 | + results = await client.search(SearchRequest(query="send a Discord DM")) |
| 45 | + entity_id = search.results[0].id # op_... or wf_... |
72 | 46 |
|
73 | | -- **Windsurf**: `~/.codeium/windsurf/mcp_config.json` |
74 | | -- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` |
75 | | -- **Claude Code**: `~/.claude.json` |
76 | | -- **Cursor**: `~/cursor/.mcp.json` |
| 47 | + # 2️⃣ load details (inspect schemas / auth, see inputs for operations) |
| 48 | + resp = await client.load(LoadRequest(ids=[entity_id])) |
| 49 | + inputs = resp.operations[entity_id].inputs |
| 50 | + print (inputsß) |
77 | 51 |
|
78 | | -For other clients, check your client's documentation for how to add MCP servers. |
| 52 | + # 3️⃣ run it |
| 53 | + result = await client.execute( |
| 54 | + ExecutionRequest(id=entity_id, inputs={"recipient_id": "123", "content": "Hello!"}) |
| 55 | + ) |
| 56 | + print(result) |
79 | 57 |
|
80 | | -```json |
81 | | -{ |
82 | | - "mcpServers": { |
83 | | - "jentic": { |
84 | | - "command": "uvx", |
85 | | - "args": [ |
86 | | - "--from", |
87 | | - "git+https://github.com/jentic/jentic-tools.git@main#subdirectory=mcp", |
88 | | - "mcp" |
89 | | - ], |
90 | | - "env": { |
91 | | - "JENTIC_UUID": "<your-jentic-uuid>" |
92 | | - } |
93 | | - } |
94 | | - } |
95 | | -} |
| 58 | +asyncio.run(main()) |
96 | 59 | ``` |
97 | 60 |
|
98 | | -__Note:__ After saving the configuration file, you may need to restart the client application (Windsurf, Claude Desktop) for the changes to take effect. |
99 | | - |
100 | | -### MCP Tool Use |
101 | | - |
102 | | -Once the MCP server is running, you can easily use the MCP tools in your LLM agent to discover and execute APIs and workflows. |
103 | | - |
104 | | -1. `search_apis`: Search for APIs in the Jentic directory that match specific functionality needs |
105 | | -2. `load_execution_info`: Retrieve detailed specifications for APIs and operations from the Jentic directory. **This will include auth information you may need to provide in your `mcpServers.jentic.env` configuration.** |
106 | | -3. `execute`: Execute a specific API or workflow operation. |
107 | | - |
108 | | -### Environment Variables |
109 | | - |
110 | | -When you are using an API that requires authentication, the `load_execution_info` tool will describe the required environment variables. You environment variables via the command line in Windsurf, although in some clients like Claude Desktop, you'll need to add them to your MCP config: |
111 | | - |
112 | | -```json |
113 | | -{ |
114 | | - "mcpServers": { |
115 | | - "jentic": { |
116 | | - "command": "uvx", |
117 | | - "args": [ |
118 | | - "--from", |
119 | | - "git+https://github.com/jentic/jentic-tools.git@main#subdirectory=mcp", |
120 | | - "mcp" |
121 | | - ], |
122 | | - "env": { |
123 | | - "JENTIC_UUID": "<your-jentic-uuid>", |
124 | | - "DISCORD_BOTTOKEN": "YOUR BOT TOKEN" |
125 | | - } |
126 | | - } |
127 | | - } |
128 | | -} |
129 | | -``` |
| 61 | +### 4. Integrate with your LLM agent (optional) |
130 | 62 |
|
131 | | -**Jentic SDK Use** |
| 63 | +If you need fully-formed tool definitions for Anthropic or OpenAI models, use the runtime helpers: |
132 | 64 |
|
133 | | -`pip install jentic` |
| 65 | +```python |
| 66 | +from jentic.lib.agent_runtime import AgentToolManager |
134 | 67 |
|
135 | | -**Jentic for Building and Executing LLM Tools** |
| 68 | +manager = AgentToolManager(format="anthropic") |
| 69 | +tools = manager.generate_tool_definitions() # pass these to the LLM |
| 70 | +result = await manager.execute_tool("discord_send_message", |
| 71 | + {"recipient_id": "123", "content": "Hi"}) |
| 72 | +print(result) |
| 73 | +``` |
136 | 74 |
|
137 | | -To provide tools to your LLM that you have selected at runtime, ask your coding agent to use the `load_execution_info` tool to retrieve the necessary information and save it to `jentic.json` at the root of your project. |
| 75 | +## Using the MCP plugin |
138 | 76 |
|
139 | | -A typical agent loop with tool use looks like this: |
| 77 | +To expose the same capabilities via MCP, follow the instructions in [`mcp/README.md`](./mcp/README.md). |
140 | 78 |
|
141 | | -```python |
142 | | -from jentic import Jentic |
143 | | - |
144 | | -class MyAgent: |
145 | | - def __init__(self): |
146 | | - self.jentic = Jentic() |
147 | | - # Generate tool definitions compatible with your LLM (e.g., "anthropic", "openai") |
148 | | - self.jentic_tools = self.jentic.generate_llm_tool_definitions("anthropic") |
149 | | - |
150 | | - async def process_message(self, user_message): |
151 | | - # Assume `messages` is your conversation history |
152 | | - # Assume `self.client` is your LLM client (e.g., Anthropic client) |
153 | | - |
154 | | - response = self.client.messages.create( |
155 | | - model='claude-3-5-sonnet-latest', |
156 | | - messages=messages, |
157 | | - tools=self.jentic_tools, # Pass the generated tools |
158 | | - ) |
159 | | - |
160 | | - while response.stop_reason == "tool_use": |
161 | | - tool_use = next(block for block in response.content if block.type == "tool_use") |
162 | | - tool_name = tool_use.name |
163 | | - tool_input = tool_use.input |
164 | | - |
165 | | - # Execute the tool using the Jentic SDK |
166 | | - tool_result = await self.jentic.run_llm_tool( |
167 | | - tool_name, |
168 | | - tool_input |
169 | | - ) |
170 | | - # ... handle tool_result and continue the conversation ... |
| 79 | +```bash |
| 80 | +uvx --from \ |
| 81 | + git+https://github.com/jentic/jentic-sdks.git@main#subdirectory=mcp \ |
| 82 | + mcp |
171 | 83 | ``` |
| 84 | + |
| 85 | +Then configure your MCP-compatible client to point at the running server (see the sub-README for sample client configs). |
0 commit comments