Metadata-Version: 2.4
Name: mcp-talentnex
Version: 0.1.2
Summary: Model Context Protocol server for TalentNex (Cauldron backend) providing candidates/challenges tools and resources
Author-email: TalentNex iVedha <talentnex.support@ivedha.com>
License: MIT
Project-URL: Homepage, https://github.com/ivedha-tech/talentnex-mcp-server
Project-URL: Repository, https://github.com/ivedha-tech/talentnex-mcp-server
Project-URL: Issues, https://github.com/ivedha-tech/talentnex-mcp-server/issues
Keywords: mcp,talentnex,cauldron,model-context-protocol,ai,nexa
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn>=0.35.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: PyJWT>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: requests-mock>=1.11.0; extra == "dev"
Dynamic: license-file

# TalentNex MCP Server (Python)

Model Context Protocol server for TalentNex (Cauldron backend). Exposes candidate and challenge data via MCP tools and resources, forwarding the Nexa Flow auth token as `Authorization: Bearer <token>` to Cauldron.

## Features
- Tools: `getCandidateById`, `searchCandidates`, `getJobRoles` (shaped like cauldron-mcp-server redactions, including `parsedResume`).
- Resources: `talentnex://candidates/recent`, `talentnex://challenges/all`.
- Transports: stdio (`mcp-talentnex`) and HTTP/SSE (`mcp-talentnex-http`).

## Requirements
- Python >= 3.10
- Env: `CAULDRON_API_BASE_URL` (e.g., `https://api.cauldron.example.com`)
- Auth: `Authorization: Bearer <token>` provided by Nexa Flow (passed through by client or HTTP header). For stdio, set `TALENTNEX_BEARER_TOKEN` or provide per-call via HTTP wrapper.

## Install
```bash
pip install mcp-talentnex
# or
uvx mcp-talentnex
```

## Run (stdio)
```bash
export CAULDRON_API_BASE_URL="https://api.cauldron.example.com"
export TALENTNEX_BEARER_TOKEN="<nexa-flow-token>"
mcp-talentnex
```

## Run (HTTP/SSE)
```bash
export CAULDRON_API_BASE_URL="https://api.cauldron.example.com"
uvx mcp-talentnex-http
# or
mcp-talentnex-http
```

HTTP endpoints (for Claude Desktop HTTP MCP):
- `GET /mcp/tools`
- `POST /mcp/tools/call` { name, arguments }
- `GET /mcp/resources`
- `POST /mcp/resources/read` { uri }
- `GET /health`

Pass `Authorization: Bearer <token>` on each HTTP call; the server forwards it to Cauldron.

## Tools
- `getCandidateById` args: { userId, companyId, candidateId, token? }
- `searchCandidates` args: { userId, companyId, q?, skills?, status?, limit?, skip?, token? }
- `getJobRoles` args: { userId, companyId, status?, limit?, skip?, token? }

If `token` is omitted, the server uses `TALENTNEX_BEARER_TOKEN` (stdio) or the HTTP Authorization header.

## Resources
- `talentnex://candidates/recent` (uses limit 20, skip 0)
- `talentnex://challenges/all` (limit 50, skip 0)

## Development (from source)
```bash
cd talentnex-mcp-server
python -m venv .venv && source .venv/bin/activate
pip install -e .[dev]
pytest
```

## Configuration
- `CAULDRON_API_BASE_URL` (required)
- `TALENTNEX_DEFAULT_LIMIT` (optional, default 20)
- `TALENTNEX_DEFAULT_SKIP` (optional, default 0)
- `TALENTNEX_BEARER_TOKEN` (fallback token for stdio)

## Packaging / Release
- Bump version in `pyproject.toml`
- `python -m build`
- `twine upload dist/*`
- Smoke: `uvx mcp-talentnex --help`

