@linkcontrata/mcp

LinkContrata's MCP (Model Context Protocol) server. Connects your AI assistant (Claude Desktop, Claude Code, …) to your LinkContrata account to search regulations, list opportunities, review projects and procurement, and create/publish opportunities — all with your own permissions (the API enforces the same per-company isolation and the same roles as the web app).

The server doesn't reimplement business logic: it translates the assistant's tools into calls to LinkContrata's JSON API (/api/v1/*), authenticating with your personal token.

(Versión en español más abajo — ver §Español.)

1. Generate an API token

In LinkContrata: Settings → API Tokens → Generate token.

• Choose a scope:
  • read — read-only (search, list, view). Recommended to start.
  • read_write — also allows creating/publishing opportunities, creating projects, submitting bids. The server rejects writes when the token is read-only.
• Copy the token (lct_…) right then: it is shown only once.

2. Configure it in your assistant

Claude Desktop / Claude Code

Add the server to your MCP config (in Claude Desktop: Settings → Developer → Edit Config):

{
  "mcpServers": {
    "linkcontrata": {
      "command": "npx",
      "args": ["-y", "@linkcontrata/mcp"],
      "env": {
        "LINKCONTRATA_TOKEN": "lct_your_token_here",
        "LINKCONTRATA_URL": "https://linkcontrata.lat"
      }
    }
  }
}

LINKCONTRATA_URL is optional (defaults to https://linkcontrata.lat). Restart the assistant and ask, e.g.: "search regulations about appeal deadlines for the award" or "list my open opportunities".

3. Tools

Read (any token): whoami, dashboard_summary, search_regulations, list_regulatory_documents, get_regulatory_document, list_opportunities, get_opportunity, list_recommendations, list_projects, get_project, list_packages, list_contracts, list_bids, get_bid.

Write (requires read_write): create_project, promote_project_to_marketplace, create_opportunity, publish_opportunity, submit_bid, send_contact_message. Destructive actions (delete) are intentionally omitted in this version.

promote_project_to_marketplace is the one-step operation to take a project to the marketplace: it creates/reuses its package, creates the opportunity and publishes it (idempotent). Backed by POST /api/v1/projects/projects/:id/promote_to_marketplace.

Security

• The token travels as Authorization: Bearer … to the API; the plaintext token is never stored server-side (only its SHA-256 hash).
• The assistant can only do what you could do on the web — the API scopes by your company and applies the policies (Pundit) on every call.
• Revoke a token anytime from Settings → API Tokens.

Development

npm install
npm run build       # compiles TypeScript to dist/
npm run typecheck   # tsc --noEmit
LINKCONTRATA_TOKEN=lct_... node dist/index.js   # runs the server (stdio)

Transport: stdio. For a remote connector on claude.ai (OAuth 2.1) see docs/MCP_PLUGIN.md in the main repo.

Español

Servidor MCP (Model Context Protocol) de LinkContrata. Conecta tu asistente de IA (Claude Desktop, Claude Code, …) con tu cuenta de LinkContrata para buscar normas, listar oportunidades, revisar proyectos y procurement, y crear/publicar oportunidades — todo con tus permisos (la API aplica el mismo aislamiento por empresa y los mismos roles que la web).

El servidor no reimplementa lógica: traduce las herramientas del asistente a llamadas a la API JSON de LinkContrata (/api/v1/*), autenticando con tu token personal.

1. Genera un token de API

En LinkContrata: Configuración → Tokens de API → Generar token.

• Elige el alcance:
  • read — solo lectura (buscar, listar, ver). Recomendado para empezar.
  • read_write — además permite crear/publicar oportunidades, crear proyectos, enviar pujas. El servidor rechaza escrituras si el token es de solo lectura.
• Copia el token (lct_…) en ese momento: no se vuelve a mostrar.

2. Configúralo en tu asistente

En Claude Desktop / Claude Code añade el servidor a tu configuración MCP (en Claude Desktop: Settings → Developer → Edit Config) con el mismo bloque JSON de arriba, poniendo tu token en LINKCONTRATA_TOKEN. LINKCONTRATA_URL es opcional (default https://linkcontrata.lat). Reinicia el asistente y pídele, por ejemplo: "busca normas sobre plazos de apelación de la buena pro" o "lista mis oportunidades abiertas".

3. Herramientas

Lectura (cualquier token): whoami, dashboard_summary, search_regulations, list_regulatory_documents, get_regulatory_document, list_opportunities, get_opportunity, list_recommendations, list_projects, get_project, list_packages, list_contracts, list_bids, get_bid.

Escritura (requiere read_write): create_project, promote_project_to_marketplace, create_opportunity, publish_opportunity, submit_bid, send_contact_message. Las acciones destructivas (borrar) se omiten a propósito en esta versión.

promote_project_to_marketplace es la operación de un paso para llevar un proyecto al marketplace: crea/reutiliza su paquete, crea la oportunidad y la publica (idempotente). Respaldada por POST /api/v1/projects/projects/:id/promote_to_marketplace.

Seguridad

• El token viaja como Authorization: Bearer … a la API; nunca se almacena el token en claro del lado del servidor (solo su hash SHA-256).
• El asistente solo puede hacer lo que tú podrías hacer en la web — la API scopea por tu empresa y aplica las políticas (Pundit) en cada llamada.
• Revoca un token cuando quieras desde Configuración → Tokens de API.

Desarrollo

Los comandos de build son los mismos del bloque Development de arriba. Transporte: stdio. Para un conector remoto en claude.ai (OAuth 2.1) ver docs/MCP_PLUGIN.md en el repo principal.