AI能力服务器

npm install uprising

my-server/
├── instructions.md       # Server instructions (optional)
├── package.json          # Metadata (optional)
├── tools/                # Executable capabilities
│   ├── example.js
│   ├── another.mdx
│   └── simple.md         # Not supported - tools need exec logic
├── resources/            # Data providers
│   ├── docs.js
│   ├── api.mdx
│   └── guide.md          # ✅ Plain markdown works!
└── prompts/              # Templated conversations
    ├── helper.js
    ├── advanced.mdx
    └── simple.md         # ✅ Plain markdown works!

npx uprising ./my-server

import { start } from 'uprising';

await start('./my-server', {
  myConfig: 'value'
});

// tools/deploy.js
import { z } from 'zod';

export default {
  title: 'Deploy Application',
  description: 'Deploy an application to a specific environment',
  inputSchema: {
    app: z.string().min(1),
    env: z.enum(['dev', 'staging', 'prod']).default('dev'),
    force: z.boolean().optional()
  },
  async exec({ app, env, force }) {
    // Your logic here
    return {
      content: [{
        type: 'text',
        text: `Deploying ${app} to ${env}${force ? ' (forced)' : ''}`
      }]
    };
  }
};

---
title: Deploy Application
description: Deploy to environments
annotations:
  category: deployment
---

<Input name="app" type="string" required label="Application Name" />
<Input name="env" type="string" default="dev" label="Environment" />
<Input name="force" type="boolean" label="Force deployment" />

<Output name="status" type="string" />
<Output name="deployedAt" type="string" />

<Exec>
  {async ({ app, env, force }, ctx) => {
    const timestamp = new Date().toISOString();
    return {
      content: [{
        type: 'text',
        text: `Deploying ${app} to ${env}${force ? ' (forced)' : ''}`
      }],
      structuredContent: {
        status: 'deployed',
        deployedAt: timestamp
      }
    };
  }}
</Exec>

<Example title="Deploy to production">
  <Call arguments={{ app: 'web-app', env: 'prod' }} />
  <Response>
    {JSON.stringify({ status: 'deployed', env: 'prod' })}
  </Response>
</Example>

// resources/docs.js
import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';

export default {
  title: 'Documentation',
  description: 'Access project documentation',
  uri: 'docs://{section}',
  async read({ params }) {
    const content = await loadDoc(params.section);
    return {
      contents: [{
        uri: params.uri,
        mimeType: 'text/markdown',
        text: content
      }]
    };
  },
  async list() {
    return {
      resources: [
        { uri: 'docs://getting-started', name: 'Getting Started' },
        { uri: 'docs://api', name: 'API Reference' }
      ]
    };
  }
};

---
title: API Documentation
description: REST API reference
uri: api://{version}/{endpoint}
mime: text/markdown
---

<Body>
  # API Endpoint: {params.endpoint}

  Version: {params.version}

  Access this endpoint at `{{ config.apiBaseUrl }}/{{ params.version }}/{{ params.endpoint }}`
</Body>

<List>
  <Item params={{ version: 'v1', endpoint: 'users' }} title="Users API" />
  <Item params={{ version: 'v1', endpoint: 'products' }} title="Products API" />
  <Item params={{ version: 'v2', endpoint: 'users' }} title="Users API v2" />
</List>

---
title: Getting Started Guide
description: How to get started
uri: resource://guides/getting-started
mime: text/markdown
author: Engineering Team
version: 1.2.0
---

# Getting Started

Welcome to {{ package.name }}!

**Guide Version:** {{ version }}
**Author:** {{ author }}
**Server Config:** {{ config.environment }}

This guide will help you get up and running quickly.

// prompts/code-review.js
import { z } from 'zod';

export default {
  title: 'Code Review Assistant',
  description: 'Help review code with specific focus areas',
  argsSchema: {
    language: z.string(),
    focusAreas: z.array(z.string()).default([]),
    severity: z.enum(['strict', 'moderate', 'lenient']).default('moderate')
  },
  async exec({ language, focusAreas, severity }) {
    return {
      messages: [
        {
          role: 'system',
          content: {
            type: 'text',
            text: `You are a ${severity} code reviewer specializing in ${language}.`
          }
        },
        {
          role: 'user',
          content: {
            type: 'text',
            text: `Please review this code. Focus on: ${focusAreas.join(', ') || 'general best practices'}.`
          }
        }
      ]
    };
  }
};

---
title: Code Review Assistant
description: Help review code
argsSchema:
  language: string
  focusAreas:
    type: array
    items: string
  severity:
    type: string
    enum: [strict, moderate, lenient]
---

<Message role="system">
  You are a {args.severity ?? 'moderate'} code reviewer specializing in {args.language}.
</Message>

<Message role="user">
  Please review this code.

  Focus areas: {args.focusAreas?.join(', ') ?? 'general best practices'}
</Message>

<Ask name="language" type="string" label="Programming Language" required />
<Ask name="focusAreas" type="array" label="Focus Areas" />
<Ask name="severity" type="string" label="Review Severity" />

<Resource uri="resource://style-guide/{args.language}" mode="embed" />

---
title: Code Review Assistant
description: Review code with AI assistance
author: Engineering Team
argsSchema:
  language: string
  severity: string
---

You are a {{ severity }} code reviewer specializing in {{ args.language }}.

Please review the following code carefully and provide feedback.

**Reviewer:** {{ author }}
**Project:** {{ package.name }}

---
title: My AI Server
version: 2.0
team: Engineering
---

# {{ title }}

Version {{ version }} - Maintained by {{ team }}

This server provides tools and resources for {{ package.description }}.

**Environment:** {{ config.environment }}
**Server Path:** {{ dir }}

## Available Capabilities

Use the tools in this server to automate deployment, access documentation, and get code review assistance.

{{ args.task }}                    # Prompt argument
{{ params.id }}                    # Resource URI parameter
{{ config.apiKey }}                # Server configuration
{{ package.name }}                 # From package.json
{{ package.version }}              # Package version
{{ title }}                        # From front-matter
{{ author }}                       # Custom front-matter field
{{ config.database.host }}         # Nested with dot notation

import { z } from 'zod';

export default {
  inputSchema: {
    name: z.string().min(1),
    age: z.number().int().positive(),
    email: z.string().email().optional(),
    tags: z.array(z.string()).default([])
  },
  exec: async ({ name, age, email, tags }) => { ... }
};

argsSchema:
  name: string                    # Simple type
  age:
    type: integer
    minimum: 0
  email:
    type: string
    format: email
  tags:
    type: array
    items: string
    default: []

// ✅ DO: Use descriptive names and validation
inputSchema: {
  deploymentTarget: z.string().min(1),
  environment: z.enum(['dev', 'staging', 'prod']),
  config: z.object({ ... }).optional()
}

// ❌ DON'T: Use JSON Schema format
inputSchema: {
  type: 'object',
  properties: { ... }  // ❌ This will error!
}

tools/
├── deployment/
│   ├── deploy.js
│   └── rollback.js
├── testing/
│   └── run-tests.js
└── utilities/
    └── format-code.js

async exec({ input }) {
  try {
    const result = await doSomething(input);
    return {
      content: [{ type: 'text', text: result }]
    };
  } catch (error) {
    // Errors are automatically caught and formatted
    throw new Error(`Failed to process: ${error.message}`);
  }
}

// tools/api-call.js
export default ({ config }) => ({
  title: 'Call API',
  description: 'Make API requests',
  inputSchema: { endpoint: z.string() },
  async exec({ endpoint }) {
    const baseUrl = config.apiBaseUrl ?? 'https://api.example.com';
    const response = await fetch(`${baseUrl}${endpoint}`);
    // ...
  }
});

// resources/user/[id].js
export default {
  title: 'User Profile',
  description: 'Get user by ID',
  uri: 'user://{id}',  // {id} from file path [id].js
  async read({ params }) {
    const user = await db.users.find(params.id);
    return {
      contents: [{
        uri: params.uri,
        mimeType: 'application/json',
        text: JSON.stringify(user, null, 2)
      }]
    };
  }
};

my-server/
├── instructions.md              # Server instructions (optional)
├── package.json                 # Metadata (optional)
│
├── tools/                       # Tools must be .js or .mdx
│   ├── simple-tool.js          # Basic JavaScript tool
│   ├── advanced-tool.mdx       # MDX with examples
│   └── nested/
│       └── subtool.js          # → tool name: "nested-subtool"
│
├── resources/                   # Can be .js, .mdx, or .md
│   ├── static-doc.md           # Plain markdown (static)
│   ├── dynamic-doc.mdx         # MDX with components
│   ├── api.js                  # JavaScript (dynamic)
│   └── users/
│       └── [id].js             # → URI: "resource://users/{id}"
│
└── prompts/                     # Can be .js, .mdx, or .md
    ├── simple.md               # Single-message prompt
    ├── complex.mdx             # Multi-message with components
    └── custom.js               # Full control

{
  exec: async (args, context) => { ... }  // Required
}

{
  name: 'custom-name',           // Override filename
  title: 'Human Title',          // Display name
  description: 'What it does',   // Description
  inputSchema: { ... },          // Zod schemas for inputs
  outputSchema: { ... },         // Zod schemas for outputs (MDX only)
  annotations: { ... }           // Custom metadata
}

async exec(args, context) {
  context.config    // Server configuration
  context.server    // Uprising instance
  context.root      // Server directory
  context.package   // package.json data
}

{
  read: async ({ params, variables }) => { ... },  // Required
  uri: 'scheme://{param}'                          // Required (or template)
}

{
  name: 'custom-name',           // Override filename
  title: 'Human Title',          // Display name
  description: 'What it provides', // Description
  template: 'scheme://{param}',  // Alternative to uri
  list: async () => { ... },     // Resource discovery
  mime: 'text/markdown'          // MIME type override
}

{
  exec: async (args, context) => { ... }  // Required
}

{
  name: 'custom-name',           // Override filename
  title: 'Human Title',          // Display name
  description: 'What it does',   // Description
  argsSchema: { ... },           // Zod schemas for arguments
  annotations: { ... }           // Custom metadata
}

{
  messages: [
    {
      role: 'system' | 'assistant' | 'user' | 'tool',
      content: { type: 'text', text: '...' },
      name: 'optional-name'  // Optional
    }
  ],
  resources: [  // Optional - resources to embed
    { uri: 'resource://...' }
  ]
}

npx uprising ./my-server

{
  "my-server": {
    "command": "npx",
    "args": ["uprising", "/absolute/path/to/my-server"]
  }
}

import { Uprising } from 'uprising';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const uprising = new Uprising('./my-server', {
  apiKey: process.env.API_KEY,
  environment: 'production'
});

await uprising.start(new StdioServerTransport());

Error: Tool "my-tool" in tools/my-tool.js must have an 'exec' function.

Error: Tool "my-tool" uses JSON Schema format for 'inputSchema', but Uprising expects Zod schemas.
  Expected: { name: z.string(), ... }
  Got: { type: 'object', properties: { ... }, ... }
  Fix: Import 'zod' and use Zod schema objects.

Error: Resource "my-resource" must have a 'read' function.

// tools/configured-tool.js
export default ({ config, server, root, package }) => ({
  title: 'Configured Tool',
  inputSchema: { ... },
  async exec(args) {
    // Access config.myValue, server, etc.
  }
});

export default {
  uri: 'resource://docs/{section}',
  async read({ params }) { ... },
  async list() {
    return {
      resources: [
        { uri: 'resource://docs/api', name: 'API Docs', title: 'API' },
        { uri: 'resource://docs/guide', name: 'Guide', title: 'User Guide' }
      ]
    };
  }
};

// resources/api/endpoints.js
export default [
  {
    name: 'users-api',
    uri: 'api://users',
    read: async () => { ... }
  },
  {
    name: 'products-api',
    uri: 'api://products',
    read: async () => { ... }
  }
];

async exec({ input }) {
  return {
    content: [{ type: 'text', text: 'Success!' }],
    structuredContent: {
      status: 'completed',
      processedAt: new Date().toISOString(),
      result: { ... }
    }
  };
}

DIAGNOSTICS='uprising:*' npx uprising ./my-server

DIAGNOSTICS='uprising:mcp' npx uprising ./my-server

{
  "name": "my-ai-server",
  "version": "1.0.0",
  "description": "Custom AI capabilities",
  "type": "module"
}

import {
  Uprising,        // Main class
  start,           // Convenience starter
  template,        // Templating helper
  Mdx              // MDX loaders (advanced)
} from 'uprising';