# Observee SDK
**The complete Observee SDK - All-in-one package for using MCPs with AI agents, authentication management for MCPs, and complete observability for MCP Builders.**
Available for both **TypeScript/JavaScript** and **Python**.
## What's Included
This SDK includes all Observee components:
- 🤖 **Agents** - MCP tool integration with LLM providers ([npm](https://www.npmjs.com/package/@observee/agents) | [pypi](https://pypi.org/project/mcp-agents/))
- 🔐 **Auth** - OAuth authentication for 15+ services ([npm](https://www.npmjs.com/package/@observee/auth) | [pypi](https://pypi.org/project/auth-mcp/))
- 📊 **Logger** - Structured logging and monitoring ([npm](https://www.npmjs.com/package/@observee/logger) | [pypi](https://pypi.org/project/mcp-logger/))
## Quick Start
### TypeScript/JavaScript
```bash
# Install everything at once
npm install @observee/sdk
# Or install individual packages
npm install @observee/agents @observee/auth @observee/logger
```
### Python
```bash
# Install individual packages (no meta-package yet)
pip install mcp-agents auth-mcp mcp-logger
# Or install all at once
pip install observee
```
### Usage Examples
#### TypeScript/JavaScript
**Option 1: Import from main package**
```typescript
import { chatWithTools, callMcpAuthLogin, Logger } from "@observee/sdk";
// Use agents
const result = await chatWithTools("Search for news", {
provider: "anthropic",
observeeApiKey: "obs_your_key",
});
// Use auth
const authResponse = await callMcpAuthLogin({
authServer: "gmail",
});
// Use logger
const logger = new Logger({ apiKey: "obs_your_key" });
logger.info("Application started");
```
**Option 2: Import from specific sub-packages**
```typescript
import { chatWithTools } from "@observee/agents";
import { callMcpAuthLogin } from "@observee/auth";
import { Logger } from "@observee/logger";
```
#### Python
```python
from observee_agents import chat_with_tools
from observee_auth import call_mcpauth_login
# Use agents
result = chat_with_tools(
"Search for news",
provider="anthropic",
observee_api_key="obs_your_key"
)
# Use auth
auth_response = call_mcpauth_login(auth_server="gmail")
print(f"Login URL: {auth_response['auth_url']}")
```
## Complete Example
### TypeScript/JavaScript
```typescript
import { chatWithTools, callMcpAuthLogin, Logger } from "@observee/sdk";
// Set up logging
const logger = new Logger({
apiKey: "obs_your_key",
service: "my-app",
});
async function main() {
try {
// Authenticate with Gmail
logger.info("Starting Gmail authentication");
const auth = await callMcpAuthLogin({
authServer: "gmail",
});
console.log("Visit:", auth.url);
// Use AI agent with tools
logger.info("Starting AI chat with tools");
const result = await chatWithTools("Search my emails for project updates", {
provider: "anthropic",
observeeApiKey: "obs_your_key",
});
console.log("AI Response:", result.content);
logger.info("AI chat completed", {
toolsUsed: result.toolCalls?.length || 0,
});
} catch (error) {
logger.error("Application error", { error: error.message });
}
}
main();
```
### Python
```python
from observee_agents import chat_with_tools call_mcpauth_login
import asyncio
async def main():
try:
# Authenticate with Gmail
logger.info("Starting Gmail authentication")
auth = call_mcpauth_login(auth_server="gmail")
print(f"Visit: {auth['auth_url']}")
# Use AI agent with tools
logger.info("Starting AI chat with tools")
result = await chat_with_tools(
"Search my emails for project updates",
provider="anthropic",
observee_api_key="obs_your_key"
)
print(f"AI Response: {result['content']}")
except Exception as error:
logger.error("Application error", {"error": str(error)})
# Run the async function
asyncio.run(main())
```
## Package Documentation
Each component has detailed documentation:
### TypeScript/JavaScript
- **Agents**: [README](https://github.com/observee-ai/observee/tree/main/agents/ts/README.md) | [npm](https://www.npmjs.com/package/@observee/agents)
- **Auth**: [README](https://github.com/observee-ai/observee/tree/main/auth/ts/README.md) | [npm](https://www.npmjs.com/package/@observee/auth)
- **Logger**: [README](https://github.com/observee-ai/observee/tree/main/logger/ts/README.md) | [npm](https://www.npmjs.com/package/@observee/logger)
### Python
- **Agents**: [README](https://github.com/observee-ai/observee/tree/main/agents/python/README.md) | [pypi](https://pypi.org/project/mcp-agents/)
- **Auth**: [README](https://github.com/observee-ai/observee/tree/main/auth/python/README.md) | [pypi](https://pypi.org/project/auth-mcp/)
- **Logger**: [README](https://github.com/observee-ai/observee/tree/main/logger/python/README.md) | [pypi](https://pypi.org/project/mcp-logger/)
### General Documentation
- [Observee Docs](https://docs.observee.ai)
## Configuration
### Environment Variables (Recommended)
Set up your environment variables:
```bash
# Core Observee configuration
export OBSERVEE_API_KEY="obs_your_key_here"
export OBSERVEE_CLIENT_ID="your_client_id"
# LLM Provider keys (for agents)
export ANTHROPIC_API_KEY="your_anthropic_key"
export OPENAI_API_KEY="your_openai_key"
export GOOGLE_API_KEY="your_google_key"
```
When environment variables are set, you can use the SDK without passing API keys to functions:
```typescript
// No need to pass observeeApiKey when OBSERVEE_API_KEY is set
const result = await chatWithTools("Search for news", {
provider: "anthropic",
});
const logger = new Logger("my-server", {
apiKey: process.env.OBSERVEE_API_KEY,
});
```
### Direct Parameter Passing
Alternatively, you can pass API keys directly to functions:
```typescript
// Pass API key as parameter
const result = await chatWithTools("Search for news", {
provider: "anthropic",
observeeApiKey: "obs_your_key",
});
const logger = new Logger("my-server", {
apiKey: "obs_your_key",
});
```
**Note**: API keys passed as parameters take precedence over environment variables.
## Features Overview
### 🤖 AI Agents (@observee/agents)
- **Multi-Provider Support**: Anthropic Claude, OpenAI GPT, Google Gemini
- **MCP Tool Integration**: 15+ pre-built tools (Gmail, YouTube, Linear, etc.)
- **Smart Filtering**: BM25, local embeddings, cloud-based filtering
- **Streaming Support**: Real-time responses
- **Conversation Memory**: Persistent chat history
### 🔐 Authentication (@observee/auth)
- **OAuth 2.0 Flows**: Gmail, Slack, Notion, Linear, GitHub, and more
- **Simple Integration**: One-line authentication
- **Secure Token Management**: Automatic storage and refresh
- **Custom Redirects**: Support for self-hosted servers
### 📊 Logging (@observee/logger)
- **Structured Logging**: JSON-based log format
- **Usage Tracking**: Monitor API usage and costs
- **Multiple Transports**: Console, file, and cloud logging
- **Performance Monitoring**: Track response times and errors
## Support
- 📖 [Documentation](https://docs.observee.ai)
- 🐛 [Issue Tracker](https://github.com/observee-ai/observee/issues)
- 💬 [Discord Community](https://discord.gg/jnf8yHWJ)
- 📧 [Email Support](mailto:contact@observee.ai)
## License
All rights reserved. This software is proprietary and confidential.
Raw data
{
"_id": null,
"home_page": null,
"name": "observee",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Observee Team <contact@observee.ai>",
"keywords": "mcp, agent, llm, anthropic, openai, gemini, tools, logging, monitoring, oauth, authentication",
"author": null,
"author_email": "Observee Team <contact@observee.ai>",
"download_url": "https://files.pythonhosted.org/packages/d2/13/00beb50996eb9f85715eaf2821afd036addbd9d327f96850f8b097f106b6/observee-0.1.20.tar.gz",
"platform": null,
"description": "# Observee SDK\n\n**The complete Observee SDK - All-in-one package for using MCPs with AI agents, authentication management for MCPs, and complete observability for MCP Builders.**\n\nAvailable for both **TypeScript/JavaScript** and **Python**.\n\n## What's Included\n\nThis SDK includes all Observee components:\n\n- \ud83e\udd16 **Agents** - MCP tool integration with LLM providers ([npm](https://www.npmjs.com/package/@observee/agents) | [pypi](https://pypi.org/project/mcp-agents/))\n- \ud83d\udd10 **Auth** - OAuth authentication for 15+ services ([npm](https://www.npmjs.com/package/@observee/auth) | [pypi](https://pypi.org/project/auth-mcp/))\n- \ud83d\udcca **Logger** - Structured logging and monitoring ([npm](https://www.npmjs.com/package/@observee/logger) | [pypi](https://pypi.org/project/mcp-logger/))\n\n## Quick Start\n\n### TypeScript/JavaScript\n\n```bash\n# Install everything at once\nnpm install @observee/sdk\n\n# Or install individual packages\nnpm install @observee/agents @observee/auth @observee/logger\n```\n\n### Python\n\n```bash\n# Install individual packages (no meta-package yet)\npip install mcp-agents auth-mcp mcp-logger\n\n# Or install all at once\npip install observee\n```\n\n### Usage Examples\n\n#### TypeScript/JavaScript\n\n**Option 1: Import from main package**\n\n```typescript\nimport { chatWithTools, callMcpAuthLogin, Logger } from \"@observee/sdk\";\n\n// Use agents\nconst result = await chatWithTools(\"Search for news\", {\n provider: \"anthropic\",\n observeeApiKey: \"obs_your_key\",\n});\n\n// Use auth\nconst authResponse = await callMcpAuthLogin({\n authServer: \"gmail\",\n});\n\n// Use logger\nconst logger = new Logger({ apiKey: \"obs_your_key\" });\nlogger.info(\"Application started\");\n```\n\n**Option 2: Import from specific sub-packages**\n\n```typescript\nimport { chatWithTools } from \"@observee/agents\";\nimport { callMcpAuthLogin } from \"@observee/auth\";\nimport { Logger } from \"@observee/logger\";\n```\n\n#### Python\n\n```python\nfrom observee_agents import chat_with_tools\nfrom observee_auth import call_mcpauth_login\n\n# Use agents\nresult = chat_with_tools(\n \"Search for news\",\n provider=\"anthropic\",\n observee_api_key=\"obs_your_key\"\n)\n\n# Use auth\nauth_response = call_mcpauth_login(auth_server=\"gmail\")\nprint(f\"Login URL: {auth_response['auth_url']}\")\n\n```\n\n## Complete Example\n\n### TypeScript/JavaScript\n\n```typescript\nimport { chatWithTools, callMcpAuthLogin, Logger } from \"@observee/sdk\";\n\n// Set up logging\nconst logger = new Logger({\n apiKey: \"obs_your_key\",\n service: \"my-app\",\n});\n\nasync function main() {\n try {\n // Authenticate with Gmail\n logger.info(\"Starting Gmail authentication\");\n const auth = await callMcpAuthLogin({\n authServer: \"gmail\",\n });\n console.log(\"Visit:\", auth.url);\n\n // Use AI agent with tools\n logger.info(\"Starting AI chat with tools\");\n const result = await chatWithTools(\"Search my emails for project updates\", {\n provider: \"anthropic\",\n observeeApiKey: \"obs_your_key\",\n });\n\n console.log(\"AI Response:\", result.content);\n logger.info(\"AI chat completed\", {\n toolsUsed: result.toolCalls?.length || 0,\n });\n } catch (error) {\n logger.error(\"Application error\", { error: error.message });\n }\n}\n\nmain();\n```\n\n### Python\n\n```python\nfrom observee_agents import chat_with_tools call_mcpauth_login\nimport asyncio\n\n\nasync def main():\n try:\n # Authenticate with Gmail\n logger.info(\"Starting Gmail authentication\")\n auth = call_mcpauth_login(auth_server=\"gmail\")\n print(f\"Visit: {auth['auth_url']}\")\n\n # Use AI agent with tools\n logger.info(\"Starting AI chat with tools\")\n result = await chat_with_tools(\n \"Search my emails for project updates\",\n provider=\"anthropic\",\n observee_api_key=\"obs_your_key\"\n )\n\n print(f\"AI Response: {result['content']}\")\n except Exception as error:\n logger.error(\"Application error\", {\"error\": str(error)})\n\n# Run the async function\nasyncio.run(main())\n```\n\n## Package Documentation\n\nEach component has detailed documentation:\n\n### TypeScript/JavaScript\n\n- **Agents**: [README](https://github.com/observee-ai/observee/tree/main/agents/ts/README.md) | [npm](https://www.npmjs.com/package/@observee/agents)\n- **Auth**: [README](https://github.com/observee-ai/observee/tree/main/auth/ts/README.md) | [npm](https://www.npmjs.com/package/@observee/auth)\n- **Logger**: [README](https://github.com/observee-ai/observee/tree/main/logger/ts/README.md) | [npm](https://www.npmjs.com/package/@observee/logger)\n\n### Python\n\n- **Agents**: [README](https://github.com/observee-ai/observee/tree/main/agents/python/README.md) | [pypi](https://pypi.org/project/mcp-agents/)\n- **Auth**: [README](https://github.com/observee-ai/observee/tree/main/auth/python/README.md) | [pypi](https://pypi.org/project/auth-mcp/)\n- **Logger**: [README](https://github.com/observee-ai/observee/tree/main/logger/python/README.md) | [pypi](https://pypi.org/project/mcp-logger/)\n\n### General Documentation\n\n- [Observee Docs](https://docs.observee.ai)\n\n## Configuration\n\n### Environment Variables (Recommended)\n\nSet up your environment variables:\n\n```bash\n# Core Observee configuration\nexport OBSERVEE_API_KEY=\"obs_your_key_here\"\nexport OBSERVEE_CLIENT_ID=\"your_client_id\"\n\n# LLM Provider keys (for agents)\nexport ANTHROPIC_API_KEY=\"your_anthropic_key\"\nexport OPENAI_API_KEY=\"your_openai_key\"\nexport GOOGLE_API_KEY=\"your_google_key\"\n```\n\nWhen environment variables are set, you can use the SDK without passing API keys to functions:\n\n```typescript\n// No need to pass observeeApiKey when OBSERVEE_API_KEY is set\nconst result = await chatWithTools(\"Search for news\", {\n provider: \"anthropic\",\n});\n\nconst logger = new Logger(\"my-server\", {\n apiKey: process.env.OBSERVEE_API_KEY,\n});\n```\n\n### Direct Parameter Passing\n\nAlternatively, you can pass API keys directly to functions:\n\n```typescript\n// Pass API key as parameter\nconst result = await chatWithTools(\"Search for news\", {\n provider: \"anthropic\",\n observeeApiKey: \"obs_your_key\",\n});\n\nconst logger = new Logger(\"my-server\", {\n apiKey: \"obs_your_key\",\n});\n```\n\n**Note**: API keys passed as parameters take precedence over environment variables.\n\n## Features Overview\n\n### \ud83e\udd16 AI Agents (@observee/agents)\n\n- **Multi-Provider Support**: Anthropic Claude, OpenAI GPT, Google Gemini\n- **MCP Tool Integration**: 15+ pre-built tools (Gmail, YouTube, Linear, etc.)\n- **Smart Filtering**: BM25, local embeddings, cloud-based filtering\n- **Streaming Support**: Real-time responses\n- **Conversation Memory**: Persistent chat history\n\n### \ud83d\udd10 Authentication (@observee/auth)\n\n- **OAuth 2.0 Flows**: Gmail, Slack, Notion, Linear, GitHub, and more\n- **Simple Integration**: One-line authentication\n- **Secure Token Management**: Automatic storage and refresh\n- **Custom Redirects**: Support for self-hosted servers\n\n### \ud83d\udcca Logging (@observee/logger)\n\n- **Structured Logging**: JSON-based log format\n- **Usage Tracking**: Monitor API usage and costs\n- **Multiple Transports**: Console, file, and cloud logging\n- **Performance Monitoring**: Track response times and errors\n\n## Support\n\n- \ud83d\udcd6 [Documentation](https://docs.observee.ai)\n- \ud83d\udc1b [Issue Tracker](https://github.com/observee-ai/observee/issues)\n- \ud83d\udcac [Discord Community](https://discord.gg/jnf8yHWJ)\n- \ud83d\udce7 [Email Support](mailto:contact@observee.ai)\n\n## License\n\nAll rights reserved. This software is proprietary and confidential.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Observee SDK - Tool usage logging, monitoring, authentication, and agent system for LLM integrations",
"version": "0.1.20",
"project_urls": {
"Bug Reports": "https://github.com/observee-ai/observee/issues",
"Documentation": "https://docs.observee.ai",
"Homepage": "https://observee.ai",
"Repository": "https://github.com/observee-ai/observee"
},
"split_keywords": [
"mcp",
" agent",
" llm",
" anthropic",
" openai",
" gemini",
" tools",
" logging",
" monitoring",
" oauth",
" authentication"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6a72540ceef40ef082be64af6db5a3531a14d90e75f688faf7c5cbd4e853ce87",
"md5": "ab5193e1d45c7d3a7a838d44fff81c6d",
"sha256": "fb73a5b70b4be67ae61ccc90cf0ff67286c9ab353449bd8034c1bb77ee0102b8"
},
"downloads": -1,
"filename": "observee-0.1.20-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ab5193e1d45c7d3a7a838d44fff81c6d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 59702,
"upload_time": "2025-07-23T22:45:54",
"upload_time_iso_8601": "2025-07-23T22:45:54.434756Z",
"url": "https://files.pythonhosted.org/packages/6a/72/540ceef40ef082be64af6db5a3531a14d90e75f688faf7c5cbd4e853ce87/observee-0.1.20-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d21300beb50996eb9f85715eaf2821afd036addbd9d327f96850f8b097f106b6",
"md5": "4558fd8739aaf262de5f1f602817f70d",
"sha256": "2370355095e2af9a31febcd0a04e44dbb4d0282bcfb1a1611a4619a559aaf7ca"
},
"downloads": -1,
"filename": "observee-0.1.20.tar.gz",
"has_sig": false,
"md5_digest": "4558fd8739aaf262de5f1f602817f70d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 50431,
"upload_time": "2025-07-23T22:45:55",
"upload_time_iso_8601": "2025-07-23T22:45:55.776747Z",
"url": "https://files.pythonhosted.org/packages/d2/13/00beb50996eb9f85715eaf2821afd036addbd9d327f96850f8b097f106b6/observee-0.1.20.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 22:45:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "observee-ai",
"github_project": "observee",
"github_not_found": true,
"lcname": "observee"
}
JSON
